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About This Manual 


Relational Database Systems, Inc., (RDS) developed 
INFORMIX-4GL (Fourth-Generation Application Development 
Language) for the database designer who' wants to create 
custom applications of database management. INFORMIX-4GL 
contains preprocessors, interpreters, and compilers that allow 
you to 


• 
Embed database creation and query statements (RDSQL) in a 
fourth-generation language (INFORMIX-4GL). 


• 
Create interactive screen forms that provide an interface 
between the user of your application and the database. 


• 
Design output reports that can list and summarize database 
information. 


The documentation for INFORMIX-4GL consists of two parts: the 
INFORMIX-4GL User Guide that introduces both RDSQL and 
INFORMIX-4GL in stages through example programs that 
increase in sophistication and subtlety, and the INFORMIX- 
4GL Reference Manual that summarizes all the syntax, rules, 
and definitions of the variables, statements, and keywords. 


This manual assumes that you have used INFORMIX-4GL and 
are familiar with the structure of relational databases. Those 
who are acquainted with the programs of INFORMIX-SQL or 
INFORM:IX-ESQL/C, other members of the RDS family of prod- 
ucts, willlecognize old friends in a new setting. You can read 
about INFORMIX-SQL in the INFORMIX-SQL User Guide and 
INFORMIX-ESQLlC in the INFORMIX-ESQLIC Programmer's 
Manual. 


The underlying file and indexing structure of the database 
tables created through INFORMIX-4GL, INFORMIX-SQL, or 
INFORMIX-ESQL/C is built on C-ISAM. For more information 
about this indexed sequential access method, see the C-ISAM 
Programmer's Manual. 
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Chapter Summary 


The INFORMIX-4GL Reference Manual is divided into the 
following sections: 


Introduction 


Chapter 1 


Chapter 2 


Chapter 3 


Chapter 4 


Chapter 5 


Chapter 6 


Chapter 7 


contains a description of the notational 
conventions used in syntax statements. 
It also includes a brief description of the 
demonstration database. 


gives the rules for programming in 
INFORMIX·4GL. It defines the data types and 
binding of program variables, describes expres- 
sions and functions, and explains error hand- 
ling and the interrelationships among all the 
INFORMIX-4GL statements. 


describes how to interact with databases using 
RDSQL, the RDS extension to the standard 
Structured Query Language (SQL). This 
chapter also explains the interrelationships 
among the various RDSQL statements. 


describes the procedure for constructing and 
compiling screen forms. 


describes the procedure for constructing and 
compiling reports. 


describes the functions in the INFORMIX-4GL 
library. 


describes the INFORMIX·4GL programming 
environment. 


contains an alphabetized description of each of 
the RDSQL and INFORMIX-4GL statements that 
you can use in an INFORMIX-4GL program. Use 
this chapter as a reference for syntax and rules 
concerning the use of these statements. 
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Appendix A 


Appendix B 


Appendix C 


Appendix D 


Appendix E 


Appendix F 


Appendix G 


Appendix H 


Appendix I 


Appendix J 


Appendix K 


Appendix L 


Appendix M 


describes the demonstration database used 
in this manual. 


describes the system catalogs that form the 
data dictionary for a database. 


describes the environment variables used by 
INFORMIX-4GL. 


lists the reserved words of INFORMIX·4GL. 


describes the upscol utility that permits you 
to establish default values for the attributes of 
the fields of your screen forms. 


describes the bcheck utility that checks and 
restores the integrity of your index files. 


describes the mkmessage utility that compiles 
the help messages for your INFORMIX-4GL 
application. 


describes the sqlconv utility that converts an 
INFORMIX database to an RDsQL-compatible 
database. 


describes the dbupdate utility that updates an 
RDSQL Version 1 database to an RDSQL Version 
2 database. 


describes the dbload utility that allows you to 
load data from other database systems or from 
raw data files into INFORMIX-4GL databases. 


contains descriptions of C functions that 
handle DECIMAL type variables in C 
programs. 


amplifies the discussion in the manual on outer 
joins. 


lists the ASCII characters in order. 
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Appendix N 


Appendix 0 


Error 
Messages 


describes modifications you can make on 
UNIX systems to your termcap file to extend 
function key definitions, to specify characters 
for window borders, and to enable 
INFORMIX-4GL programs to interact in color 
with your terminal. 


describes the dbschema utility that you can 
use to output the RDSQL statements necessary 
to replicate an individual table or an entire 
database. 


contains an extensive listing of error codes, 
explains their meaning, and suggests remedies 
for correcting the errors. 


Syntax Conventions 


This section explains how to interpret the listings of statement 
syntax that appear throughout this manual. 


ABC 
Enter any term in the syntaxin uppercase letters 
exactly as shown, disregarding case. Such terms are 
keywords. For example, 


CREATE INDEX indname 


means you must enter CREATE INDEX or create 
index without adding or deleting spaces or letters. 


abc 
Substitute a value for any term that appears in 
lowercase italic letters. In the previous example, 
you should substitute a value for indname. In each 
statement description in Chapter 7, the section 
"Explanation" describes what values you can 
substitute for italicized terms. 


( ) 
Enter parentheses as shown. They are part of the 
syntax of a statement, not special symbols. 


Introduction-8 Syntax Conventions 


[ ] 
Do not enter brackets as part of a statement; they 
surround any part of a statement that is optional. 
For example, 


CREATE [UNIQUE] INDEX 


indicates that you may enter either CREATE INDEX 
or CREATE UNIQUE INDEX. 


Select one of the options shown. The vertical bar 
indicates a choice among several options. For 
example, 
' 


[ONE I TWO [THREE] I FOUR] 


means that you can enter either ONE or TWO or 
FOUR arid that, if you enter TWO, you may also 
enter THREE. (Because the choices are enclosed in 
square brackets, you can also choose to omit them 
completely.) 


I I 
Choose one of the listed options. When the optiuns 
are enclosed in braces and separated by vertical 
bars, you must select one of the options. For 
example, 


lONE I TWO I THREE) 


means that you must enter ONE, or TWO, or THRiE 
and that you may not enter more than one selection. 


ABC 
Omit or use an option that is underlined. When one 
of several options is the default option, it appears 
underlined. For example: 


[CHOCOLATE I VANILLA I STRAWBERRY] 


means that you may select any of the three options, 
but that if you do not enter one of them, VANILLA is 
the default. 
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Enter additional items like those preceding the 
ellipsis, if you want. The ellipsis indicates that 
the immediately preceding item may be repeated 
indefinitely. For example, 


statement 


means that there can be a series of statements 
following the one that is listed. 


Getting Started with INFORMIX-4GL on DOS 
Systems 


To start working with INFORMIX-4GL on DOS systems, be sure 
that your computer is up and running, and that the operating 
system prompt appears on your screen. 


To compile or execute programs that use INFORMIX-4GL, you 
must perform two steps: 


1.. Load the database agent. The database agent is the part 
of OOORMIX-4GL that performs the data access and file- 
manipulation tasks necessary to complete your database 
management operations. 


2. Compile and run your INFORMIX-4GL programs. 


Loading the Database Agent 


To load the database agent, enter 


startsql 


You need to execute this command only once per session. 
The database agent remains in memory until you execute 
the command 


exit 
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from the command line. When you execute this command, it 
removes the database agent from memory. Because the data- 
base agent requires space in memory, you should remove it 
when you have completed all the desired INFORMIX-4GL, or 
other SQL, operations. This frees memory for running other 
programs on your system. 


If you attempt to load the database agent when it is already 
installed in memory, INFORMIX-4GL issues the message 
5TART5QL has already been executed. 


Entering INFORMIX-4GL 


After you have loaded the database agent, enter 


i4ql 


If you try to run i4ql without first loading the database agent, 
INFORMIX-4GL issues the message Please run 5TART5QL. 


If you want to check to see if the database agent has been 
loaded, enter 


set 


This gives you a -list of your environment variables. If the 
database agent has been loaded, the variable SQLCADDR 
is listed. The following is an example of SQLCADDR as it 
appears in a list ofenvironment variables. The numbers 
represent the address in memory where the database agent 
is loaded. 


SQLCADDR=333744a8 
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The Demonstration Database 


Most of the examples in this manual are based on the stores 
demonstration database. This database, described and listed 
in detail in Appendix A, involves a wholesale sporting goods 
firm that maintains a stock of equipment and fills orders to 
retailers. You can create the stores database in the current 
directory by typing i4gldemo. This shell script removes any 
database labeled stores and installs the demonstration 
database. 


The stores database contains six tables: 


customer 


orders 


items 


stock 


manufact 


state 
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contains information about the retail stores 
that purchase sporting supplies. 


contains information about the individual 
orders from the retail stores. 


contains information about the items that 
make up an order. 


contains information about the variety of 
sporting goods available. 


contains information about manufacturers 
of sporting goods. 


contains the names and abbreviations of the 
states. 
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INFORMIX-4GL Programming 
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Chapter Overview 


An INFORMIX-4GL program consists of a series of English-like 
statements that obey a well-defined syntax. This chapter 
describes the syntax rules that apply and gives an overview of 
those statements that do not apply directly to a database. It 
also describes how the program statements are compiled into 
an executable program. 


Language Conventions 


The INFORMIX-4GL programming language contains identifiers, 
keyv-,'ords, constants, operators, and expressions. It is com- 
pletely free-form, like C or Pascal, and ignores extra spaces, 
tabs, new lines, and comments. When necessary, it uses the 
keyword END in association with the statement type to ter- 
minate a statement; otherwise, it has no statement terminators 
such as the semicolon. 


Comments 


Comments in an INFORMIX-4GL program begin with the left 
brace: and end with the right brace I. You may, alternatively, 
use the # sign to begin a comment. In this case, the comment 
terminates at the end of the line. You may not nest comments. 
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INFORMIX-4GL Identifiers 


INFORMIX·4GL deals with a number of different kinds of objects. 
These include local and global program variables, constants, 
screen forms, functions, and reports. With the exception of 
constants, all of these must have an INFORMIX-4GL identifier as 
a name. An INFORMIX-4GL identifier is a sequence of letters, 
digits, and underscores (_). The first character must be a 
letter or an underscore. Only the first eight characters are 
significant, and the case of letters is ignored. Identifiers must 
not be the same as keywords (see Appendix D for a complete 
list of keywords). 


INFORMIX-4GL identifiers may be the same as RDSQL identifiers, 
but such use requires special attention when you use the 
identifier in an RDSQL statement (see Chapter 2 for a discussion 
of RDSQL statements, objects, and identifiers). 


Scope of Identifiers 


Program variables may be either local or global. Local vari- 
ables must be defined within a routine and have a scope only 
for that routine. You must define global variables either prior 
to the main program module or in a separate globals file. All 
program files using those global variables must include the 
statement GLOBALS "globals-filename", where globals-filename 
contains the definitions of the global variables. 


Forms, cursors, functions, reports, and some statements have 
identifiers but are not program variables (see Chapter 2 for the 
definition of cursors and statement identifiers). The scope for 
identifiers of functions and reports is the entire program. The 
scope for form, cursor, and statement identifiers is the entire 
file in which they are used. 
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Constants 


There are several kinds of constants: strings, integers, floating 
numbers, and dates. INFORMIX-4GL provides three pre-defined 
constants: TRUE = 1, FALSE = 0, and NOTFOUND = 100. 
H also permits the assignment of the value NULL to variables 
and to database columns. NULL values are distinct from blank 
strings or zeros for numeric variables and columns and repre- 
sent unknown values. See the section "NULL Values" in 
Chapter 2 for details about the behavior of NULL values in 
expressions. 


String Constants 


String constants are sequences of up to 80 characters enclosed 
within double quotes. The constant must be written on a sin- 
gle line (no embedded new lines). You may create longer string 
variables by concatenating string constants. To include a 
double quote in a string, precede the double quote with the 
backslash or repeat the double quote: 


"Enter \"y\" 
to 
select 
this 
row" 


or 


"Enter 
....y'''' 
to 
select 
this 
row" 


The single quote has no special significance in string constants. 


Integer Constants 


Integer constants must be expressed in decimal notation 
without embedded commas and without a decimal point. You 
may precede the integer with a minus or plus sign, but there 
may be no space, tab, or new line between the sign and the 
first digit: 


15 
-12 
13938 
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Floating Numeric Constants 


Non-integer numeric constants are expressed only in base 10 
with a decimal point. You may use exponential notation as 
well: 


123.456 
1.23456e2 
123456.0e-3 


Date Constants 


DATE constants must be enclosed within double quotation 
marks and can be expressed either with the format mm/dd/yy 
or with mm/dd/yyyy. mm stands for the month (l or 01 for 
JanuarY,2 or 02, for February, and so on). dd stands for the 
day of the month (from 1 to the maximum for that particular 
month). yy and yyyy stand for the year. When you use only 
two digits for the year, INFORMIX-4GL assumes that you intend 
to enter a year beginning with the digits "19." 
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Program Variables 


Information transfer among a screen, report, and database 
occurs through program variables. You must define the data 
storage required by a program variable before you can use that 
variable in an INFORMIX·4GL program. You do this by assigning 
an identifier to the variable and associating it with a data type. 
using the DEFINE statement (see Chapter 7 for details). 


Data Types 


INFORMIX·4GL variables must have one of the following 
data types: 


SMALLINT 
INTEGER 
DECIMAL[(m[, nj)] 
SMALLFLOAT 
FLOAT 
MONEY[(m[, nj)] 


SMALLINT 


CHAR[(n)) 
DATE 
LIKE table.column 
RECORD [LIKE table,*] 
ARRAY[ij, k) OF type 


These are whole numbers in the range from - 32,767 to 
+32,767. 


INTEGER 


These are whole numbers in the range from -2,147,483,647 to 
+2,147,483,647. 
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DECIMAL[(m[, n])] 


These are decimal floating-point numbers with a total of m 
«= 32) significant digits (the precision) and n «= m) digits 
to the right of the decimal point (the scale). When you give 
values for both m and n, the decimal variable obeys fixed-point 
arithmetic. All numbers less than 0.5 X lO-n in absolute value 
have the value zero. The largest absolute value of a variable of 
this type that can be stored without an error is 
10m-n _ 10-n. 


The second parameter is optional and, if missing, INFORMIX-4GL 
treats the variable as a floating decimal. This means that 
DECIMAL(m) variables have a Rrecision of m and a range in 
absolute value from 10-128 to 10 26. When printed without 
other formatting instructions, DECIMAL(m) variables have 
two decimal places to the right of the decimal point (and an 
exponent, if necessary). If you designate no parameters, 
INFORMIX-4GL treats DECIMAL as DECIMAL(l6), a floating 
decimal. 


SMALLFLOAT' 


These are binary floating-point numbers corresponding to the 
float C data type. 


FLOAT 


These are binary floating-point numbers corresponding to the 
double C data type. 


MONEY[(m[, n])] 


Like the DECIMAL data type, the MONEY data type can also 
take two parameters. The limitation on values for columns of 
type MONEY(m, n) is the same as for columns of type 
DECIMAL(m, n). The difference between them is that 
MONEY type variables are displayed with a dollar sign. The 
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type MONEY(m) is defined as DECIMAL(m, 2) and, if no 
parameter is given, MONEY is taken to be DECIMAL(16, 2). 
Regardless of the number of parameters, INFORMIX-4GL always 
treats the data type MONEY as a fixed decimal number. 


CHAR(n) 


These are character strings of length n (where 1 <= n <= 
32,767). You can refer to substrings of CHAR type variables in 
LET, ERROR, MESSAGE, and PROMPT statements with the 
notation char-variable[m,n} which selects the mth through the 
nth components of the variable char-variable. 


DATE 


These are dates entered as a character string in one of the 
formats described earlier in the section "Date Constants." 
INFORMIX-4GL stores a DATE variable as an integer whose 
value is the number of days since December 31, 1899. 


LIKE table.column 


You may define the data type of a program variable indirectly 
by indicating that it should have the same data type as a 
column in the database. If the column has type SERIAL (see 
Chapter 2 for the definition of this data type), INFORMIX·4GL 
assigns the variable the data type INTEGER, but enforces 
none of the other restrictions on SERIAL data types. 


RECORD 


This data type describes a set of variables of possibly differing 
data types, including other records. You can refer to individuaf 
elements as record_name.element_name and, under most cir- 
cumstances, to the entire set as record-name. *. See the section 
"The THRU Keyword and the .* Notation," later in this 
chapter, for the limitations on using record-name. *. 
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You may define a record by listing its elements and their types 
or by defining it to be LIKE table. *, where table is a table in 
the database. If defined LIKE table. *, the elements of the 
record have the same names as the columns of table and the 
same corresponding data types. 


ARRAY[i, j, k] OF type 


This is a data type that describes i X j X k variables of the 
same data type. ARRAY variables can have from one to three 
dimensions. You can have an array of records, but not an 
array of arrays. The square brackets are required and do not 
represent an option. 


If char-array[ij,k] is an array of CHAR type, you select 
a substring of one of its components with the char- 
arra.v[ij,k][m,n] notation. In this example, ij,k are indexes 
into the array, m is the starting position of the substring, 
and n is the stopping position of the substring. 


Data Conversion 


INFORMIX-4GL performs. data-type conversion without objection 
whenever the process makes sense. You may assign a numeric 
expression to a CHAR variable and INFORMIX·4GL converts the 
resulting number to a string. If you use a string representation 
of a number or a date in an arithmetic expression, 
INFORMIX-4GL converts the string or date to an appropriate 
number. INFORMIX·4GL produces an error message only if the 
conversion could not be made. For example, INFORMIX-4GL 
converts the string "123.456" to the number 123.456 in an 
addition, while the string "John" produces an error. 
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INFORMIX-4GL carries out all arithmetic in an arithmetic expres- 
sion in type DECIMAL. The type of the resulting variable 
determines the format of the stored or printed result. The fol- 
lowing rules apply to the precision and scale of the DECIMAL 
variable that results from an arithmetic operation on two 
numbers: 


• 
All operands, if not already DECIMAL, are converted to 
DECIMAL, and the resulting number is DECIMAL. 


Convert Type 


FLOAT 
SMALLFLOAT 
INTEGER 
SMALLINT 


To 


DECIMAL(l6) 
DECIMAL(8) 
DECIMAL(lO,O) 
DECIMAL(5.0) 


• 
The precision and scale of the result of an arithmetic opera- 
tion depend on the precision and scale of the operands and 
on the type of arithmetic expression. The rules are sum- 
marized in the table at the end of this section for arithmetic 
operations on operands with definite scale. When one of 
the operands has no scale (floating decimal), the result is a 
floating decimal. 


• 
If the operation is addition or subtraction, INFORMIX-4GL 
adds trailing zeros to the operand with the smallest scale 
until the scales are equal. 


• 
If the type of the result of an arithmetic operation requires 
the loss of significant digits, INFORMIX-4GL reports an error. 


• 
Leading or trailing zeros are not considered significant 
digits and do not contribute to the determination of 
precision and scale. 
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In the following table, let p and s be the precision and scale of 
the first operand. and let p.: and s: be the precision and scale of 
the. second operand. 
- 
- 


Operation 


Addition and 


Subtraction 


Precision and Scale of Result 


Precision: 
MIN(32, MAX(P j - SI' P2- S2) 
+ MAX(sj' S2) + 1) 


1\1ultiplication 


Division 


Precision: 


Scale 


Precision: 


MIN(32, PI+ P2) 


S + S 
I 
2 


32 


Scale: 
32 - P + s - s (cannot be negative) 
j 
I 
2 


Operators and Expressions 


Expressions in INFORMIX-4GL can be categorized as numeric, 
string, and Boolean. Numeric expressions can be either integer 
(evaluating to INTEGER or SMALLINT) or non-integer 
(evaluating to FLOAT, SMALLFLOAT, MONEY, or DECI- 
MAL). Because of the automatic conversion capability of 
INFORMIX-4GL, DATE type variables can occur in either integer 
or string expressions. Numeric variables can occur in either 
numeric or string expressions. String variables that are charac- 
ter representations of numbers are converted to numbers when 
used in numeric expressions. A string variable that is not a 
character representation of a number will cause an error if used 
in a numeric expression. 
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Numeric Expressions 


A numeric expression consists of a numeric constant, variable, 
column name, or function that returns a numeric value, or one 
of these connected by one of the following arithmetic operators 
to a numeric expression: 


Operator 


** 


* 
/ 
mod 


+ 


Operation 


Exponentiation 


Multiplication 
Division 
Modulus 


Addition 
Subtraction 


String Expressions 


A string expression is a· string constant, a CHAR type variable, 
a CHAR type column, or a function returning a CHAR type, or 
combinations of these combined or altered by the following 
string operators: 


Operator 


[m,n] 


USING 
CLIPPED 


Operation 


Concatenation . 
Substring where m is the starting 
position and n is the ending position 
Formatting 
Drop trailing blanks 


Numeric constants, variables, and columns are converted to 
their character representation when used in string expressions. 
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Boolean Expressions 


A Boolean expression evaluates to true or false (or unknown if 
NULL values are involved) and can take any of the following 
forms: 


• 
expr rel-op expr 


Where expr is an expression and rel-op is a relational 
operator: 


Operator 


!= or <> 
> 
>= 
< 
<= 


Operation 


Equal 
Not equal 
Greater than 
Greater than or equal 
Less than 
Less than or equal 


For string expressions, greater than means after in the 
ASCII collating order, where lowercase letters are after 
uppercase letters, which are after numerals. For DATEs, 
greater than means later in time. 


• 
string-expr [NOT] LIKE string-expr 


• 
string-expr [NOT] MATCHES string-expr 


• 
expr IS [NOT] NULL 
------ 
• 
expr [NOT] BETWEEN expr AND expr 


• 
expr [NOT] IN (litems I SELECT-statementl) 


• 
expr rel-op (ALL I ANY I SOME: (SELECT-statement) 


• 
EXISTS (SELECT-statement) 


The last four expressions apply only in WHERE clauses of 
SELECT statements (see Chapter 7 for details). 
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Boolean expressions may be compounded with the operators 
NOT, AND, and OR: 


[NOT] Boolean-expr [lAND I ORl Boolean-expr] 


Expressions in INFORMIX-4GL Statements 


For the CASE, IF, and WHILE statements in INFORMIX-4GL, 
true is any non-zero number and false is zero. In these state- 
ments a numeric expression can be used where a Boolean 
expression is called for. A Boolean expression can be used 
where a numeric expression would be expected, yielding 1 or O. 
A string expression that is a representation of a number can be 
used anywhere that a numeric expression is allowed. If you use 
a string expression where a Boolean expression is expected and 
the string expression does not represent a number, it will be 
evaluated as zero or false. 


If a Boolean expression contains a NULL value, it has an 
unknown truth value and, yet, will be treated as false in 
INFORMIX-4GL statements. This can lead to unfamiliar conse- 
quences. If a is a Boolean expression, the compound expres- 
sion a OR NOT a would, in two-valued logic, be tautologically 
true. If a contains a NULL value, its truth value is unknown. 
So is the truth value of NOT a. INFORMIX-4GL treats both as 
false and their combination with OR as well. If there is any 
chance that a variable may have a NULL value, you should test 
it before using it in a Boolean expression. See the section 
"NULL Values" in Chapter 2 for more details. 
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Binding to Database and Forms 


Regardless of how you have defined them, there is no implicit 
relationship between program variables, screen fields, and data- 
base columns. Even when a variable lname is defined to be 
LIKE customer.lname, changes to the program variable do 
not imply any change in the column value. Similarly, even 
though you created a screen field customer.lname using the 
same database column as a model, there is no inherent connec- 
tion between the program variable and the field. You must 
indicate the binding explicitly in any statement that connects 
program variables to screen forms or to database columns. 


The following two statements take input from the screen and 
insert the value entered on the screen into the database. The 
@ sign tells Il"FORMIX·4GL that the first lname is the name of a 
database column. 


INPUT 
Iname 
FROvl c us tome r . Iname 
INSERT 
INTO customer 
(@Iname) 
VALUES 
(Iname) 


Some statements permit temporary binding through the 
identity of the variable name and the screen field name (see 
the individual statement descriptions in Chapter 7 for the 
appropriate syntax). You could use the following statement 
in place of the first one in the previous example: 


INPUT BY NAME 
Iname 
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The THRU Keyword and the. * Notation 


INFORMIX-4GL provides two devices to simplify the writing of 
INFORMIX·4GL statements that refer to elements of a record or 
columns of a table. One of these involves the keyword THRU 
(or THROUGH), and the other, the .* notation. 


INITIALIZE pr_rec.element4 
THRU pr_rec.element8 TO NULL 


The first statement sets to NULL the value of the 
program variables pr_rec.element4, pr_rec.element5, 
pr_rec.element6, pr_rec.element7, and 
pr_rec.element8. The second displays all the values 
of the record pr_ rec on the screen in the fields described 
by the screen record sc_ rec (see Chapter 3 for a description 
of screen records). 


With one exception, discussed at the end of this section, these 
devices are "shorthand" for writing out a partial or full list of 
record elements or the columns of a table with commas 
separating the individual items. The order of the items in the 
list is the order they had when defined. There are, however, 
the following limitations on their use: 


• 
You cannot use THRU in reference to columns of tables. 
There is no "shorthand" for a partial listing of columns of a 
table. 


• 
In the definition of a screen record, THRU runs through all 
the fields in the order they are listed in the Attributes 
Section of the form specification, from the first named to 
the last. 
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ATTRIBUTES 


f002=tab1.aa; 
f 003=tab 1 . bb ; 
f004=tabl.cc; 
f005=tab2.aa; 
f006=tab2.bb; 
f007=tab3.aa; 
f008=tab3.bb; 
f009=tab3.cc; 


INSTRUCTIONS 
SCREEN RECORD sc__rec (tab1.cc 
THRU tab3.bb) 


The excerpt above from a form specification file leads to the 
following list of elements of sc_rec: 


tab1.cc 
tab2.aa 
tab2.bb 
tab3.aa 
tab3.bb 


• 
You cannot use THRU to indicate a partial list of screen 
record elements when displaying to a form or inputting 
from a form. 


• 
You cannot use either THRU or the.* notation on a record 
that contains an array as elements. For example, you can- 
not use myrec.* to refer to all the elements of a record 
defined as follows: 


DEFINE myrec 
RECORD 
r i 
INTEGER, 
ra 
ARRAV[2] 
OF 
INTEGER 
END RECORD 


You can use these "shorthands," however, for records that 
contain records as elements. 


• 
You may not use THRU or the .* notation in the argument 
list when defining a function or report. You can, however, 
list a record as an argument to a function or report. 
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The exception to .* expanding to a list occurs when you use it 
in an RDSQL UPDATE statement. The notation 


UPDATE 
table1 
SET 
table1.· 
= 
pr_rec.· 


is expanded by INFORMIX-4GL to the proper syntax 


UPDATE 
lable1 
SET 
table1.col1 
lable1.col2 
p r_r e c . e I erne n I 1 , 
P r_r ec . e I erne n I 2 . 


with all SERIAL columns omitted. 


INFORMIX-4GL Statements 


Do 


IF (Pr-rx:c ...*) 


There are eight different statement types in INFORMIX-4GL that 
do not deal with the database. 


Variable Definition 


All program variables must be defined before they can be used. 


DEFINE 
associates an INFORMIX·4GL identifier with a 
data type. DEFINE statements must be the 
first statements within a routine or must be 
within a GLOBALS statement. 
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Assignment 


You can assign values directly to program variables with one of 
two statements: 


LET 
assigns the value of an expression to a simple 
program variable or to a component of an 
array or a record. You may not use a single 
LET statement to assign values to an entire 
record or an array. 


INITIALIZE 
assigns default or NULL values to a program 
variable. You can set default values for all 
columns in your database (through the upscol 
utility; see Appendix E for details) and use the 
INITIALIZE statement to assign these values 
to simple or record variables. 


Program Organization 


INFORMIX-4GL programs can have three different types of 
routines: MAIN, FUNCTION, and REPORT. They may also 
contain global declaration statements. 


MAIN 
contains one or more INFORMIX-4GL statements 
and must occur once, and only once, in every 
INFORMIX-4GL program. INFORMIX-4GL passes 
program control initially to the MAIN routine 
when you execute your program. The last 
statement in the MAIN routine must be the 
END MAIN statement. After INFORMIX-4GL 
executes the END MAIN statement, it 
terminates the program. 
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I. 


FUNCTION 
contains a sequence of INFORMIX-4GL 
statements that perform a desired task and 
terminates with the END FUNCTION state- 
ment. A function can return zero or more 
values to the routine that called it. You can 
pass the values of variables to functions as 
parameters. 


REPORT 
contains the format and output specification 
for a report. 


GLOBALS 
identifies those program variables that have 
global scope. 


There must be one and only one MAIN routine, and there may 
be only one GLOBALS statement that includes DEFINE state- 
ments. There is no restriction on the number of FUNCTION 
or REPORT segments. You may place all segments in a single 
system file, put each segment in a separate file, or any 
combination in between. A system file containing a program 
segment is called a module. 


If there is a GLOBALS statement containing DEFINE state- 
ments, it must either be in a module by itself or be the first 
statement (or the second if there is a DATABASE statement) 
in the module containing the MAIN segment. Any module 
containing routines that refer to global variables must begin 
with a GLOBALS statement giving the pathname of the 
module that defines the global variables. (See the GLOBALS 
statement in Chapter 7 for full details.) 


Modules may be compiled separately and linked later, permit- 
ting you to create a library of INFORMIX-4GL functions and to 
call the;m from different modules. In addition, your program 
can call C functions. See the section "C Functions," later in 
this chapter, for the rules that C functions must obey if they 
are called by INFORMIX-4GL programs. 
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Program Flow 


I~FORMIX-4GL has many statements that control the flow of a 
program. These statements are included in INFORMIX-4GL 
because they simplify the programming process. 


CALL 
is used to call a function that returns zero or 
more values. You may only use a function that 
returns a single value within an expression. 


FOR 
begins an indexed loop of statements (ended 
by END FOR) that will be executed until the 
index reaches a programmer-supplied value. 


FOREACH 
begins a loop of statements (ended by END 
FOREACH) that will be executed for each row 
that is returned by a query of the database. 


WHILE 
begins a loop of statements (ended by END 
WHILE) that will be executed until a 
programmer-supplied Boolean expression 
becomes false. 


CONTINUE 
permits a premature cycling of a loop or menu. 


EXIT 
permits a premature exit from a FOR, 
FOREACH, WHILE, MENU, INPUT, or 
CASE statement, or from the entire program. 


IF 
executes one or more statements conditionally 
(ended by END IF). 


CASE 
executes a different sequence of statements 
(ended by END CASE) depending upon the 
current value of an expression. 


GOTO 
passes program control immediately to a 
designated place in the program. 


LABEL 
marks the place in the program where a GOTO 
statement can pass control. 
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SLEEP 


RUN 


causes the program to pause for a specified 
length of time. 


executes an operating system program and 
returns control to the INFORMIX-4GL program. 


Screen Interaction 


The next eighteen statements allow the program to interact 
with the screen. The first statement constructs a menu, and 
the next five provide control over clearing the screen, printing 
messages, retrieving user input, and setting up default values 
for screen parameters, special keys, and help files. The next 
three are window management statements. The last nine 
handle the entry and retrieval of data from screen forms. 


MENU 


CLEAR 


ERROR 


MESSAGE 


PROMPT 


OPTIONS 


creates a ring menu with help lines, asso- 
ciated help screens, and a description of 
program behavior for each menu option. 


optionally clears particular screen fields, 
all screen fields, the entire screen, or a 
window. 


prints a message in reverse video on the 
Error Line and rings the terminal bell. 


prints a message on the Message Line. 


prints a message on the Prompt Line and 
returns the user's response. 


specifies the MESSAGE, PROMPT, 
FORM, and COMMENT lines relative to 
the screen or current window, as well as 
any key and help-file designations. You 
can also specify a new ERROR line with 
the OPTIONS statement, but the error 
line remains relative to the screen. 
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OPEN WINDOW 


CURRENT 
WINDOW 


creates a window, with or without a 
border, at a given location and makes it 
available for use. You can explicitly 
specify the size of the window, or let 
INFORMIX-4GL determine the size of the 
window from a given screen form. 


specifies the current or "topmost" 
window. All input and output is done in 
the current window. 


CLOSE WINDOW 
closes the window that you specify, 
restoring the "topmost" window (of those 
that remain) as the current windov.·. 


OPEN FORM 
opens the compiled screen form and 
associates an INFORMIX-4GL identifier 
with the form. 


DISPLAY FORM 
displays the named form on the screen or 
in a window, displacing whatever was on 
the screen or window below the Form 
Line. 


CLOSE FORM 
closes the file containing the named 
screen form and releases its association 
with the INFORMIX-4GL identifier. 


CONSTRUCT 
takes user input from a screen form and 
creates a character string that can be 
used as the WHERE clause of a 
SELECT statement. This is the 
INFORMIX-4GL mechanism for performing 
a query-by-example. 


DISPLAY 
displays expressions and variables in 
fields of a screen form, at a specific posi- 
tion on the screen, in a window, or on the 
next line. 
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DISPLAYARRAY displays a program array to a screen 
array and allows scrolling through the 
array. 


INPUT 


INPUT ARRAY 


SCROLL 


Report Generation 


takes user-entered data from a screen 
form and puts the data into program 
variables. You can specify sequences of 
statements to be executed during the 
INPUT statement before or after the 
cursor enters any field or after the user 
indicates that entry is complete. You can 
also trap function or control keys and 
specify an appropriate sequence of 
statements. 


is an extension of the INPUT statement 
that takes data entered by a user into a 
screen array and puts the information 
into an array of program variables. The 
user can scroll through the array, insert 
new rows into the array, and delete rows 
from the array by using function keys. 


moves data in a screen array up or down. 


There are three statements in INFORMIX-4GL that control report 
writing. 


START REPORT 
signals INFORMIX-4GL to initialize the 
report. Optionally, you may specify the 
output device in the START REPORT 
statement. 
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OUTPUT TO 
REPORT 


FINISH REPORT 


passes a row of the report variables to 
the report. This statement is usually 
found within a FOREACH loop where 
the report row is the current row of a 
query. 


handles the end of report summaries and, 
if necessary, second passes through the 
data so that aggregate values can be 
calculated. 
. 


Error and Exception Handling 


INFORMIX-4GL allows you to trap runtime errors and warnings 
and user-entered interrupts (usually DEL or CONTROL-C) and 
quits (CONTROL-\). The default conditions are that errors, 
interrupts, and quits cause immediate program termination, 
while warnings are ignored. You can change these conditions 
with the following commands: 


WHENEVER 
allows you to trap errors or warnings and to 
instruct INFORMIX-4GL to call a function, go to 
a label, terminate the program, or ignore the 
problem. In the last case, you must test for 
errors explicitly after every statement where an 
error would produce difficulties in your 
application. 


DEFER 
allows you to prevent INFORMIX-4GL from ter- 
minating a program when the user presses the 
INTERRUPT or QUIT keys. If you choose 
this option, the interrupt and/or quit will 
terminate INPUT, INPUT ARRAY, 
CONSTRUCT, and PROMPT statements, 
but will not terminate the program. You 
must explicitly check the global variables 
INT_FLAG and QUIT_FLAG to determine 
whether the user has pressed interrupt or quit 
after these statements. 
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Error Handling 


INFORMIX-4GL sets the global variable status following the 
execution of every RDSQL or form-related INFORMIX-4GL state- 
ment. status is zero when the statement executes correctly, 
negative when there is an error, and equal to NOTFOUND 
(= 100) when you attempt a FETCH outside the range of the 
active list of rows or when a SELECT statement can find no 
rows (see Chapter 2 for more information on the FETCH and 
SELECT statements). There are three library routines avail- 
able to the INFORMIX-4GL programmer to identify errors from 
the status variable (see Chapter 5 for a description of library 
routines). 


The WHENEVER statement is designed to trap errors and 
warnings in the execution of other statements. RDSQL indicates 
errors and warnings by supplying values for the global record 
SQLCA. See Chapter 2 for a description of the SQLCA record. 


The WHENEVER statement is "shorthand" for writing an 
IF-THEN statement after every RDSQL or form-related state- 
ment that follows the WHENEVER statement in the current 
source-code module. The CONTINUE option tells 
Il"FORMIX-4GL to stop inserting an IF-THEN statement after 
the subsequent statements. The default is STOP for ERROR 
and CONTINUE for WARNING. In the default situation, the 
code generated by INFORMIX-4GL tests for errors, but not 
warnings, after every INFORMIX-4GL statement. 


The scope of a WHENEVER ERROR statement is the module 
(or file) in which it occurs and from the position of the 
WHENEVER ERROR statement to the next WHENEVER 
ERROR statement in the module (or to the end of the module 
if there are no more WHENEVER ERROR statements). The 
scope of the WHENEVER WARNING statement is the same. 
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If you do not specify WHENEVER ERROR CONTINUE, the 
STARTLOGO function causes the routine name, the error 
code, and the corresponding error message to be written to a 
designated error file every time an error occurs. The syntax for 
STARTLOGO is 


CALL STARTLOG(filimame) 


where filename is a quoted string that is the name of the error 
log file or a CHAR variable that evaluates to the name of the 
error log file. If you do not want the error log file to reside in 
the current directory, you must specify a pathname. 


Another library function ERRORLOG(message) appends the 
quoted string or CHAR variable message to the error log. This 
function allows you to write directly to the error log file. 


There are three other library routines that deal with errors (see 
Chapter 5 for a full description of library functions): 


ERR_PRINTO 
If passed the error code, will print the 
message on the Error Line. 


ERR_GETO 
If passed the error code, will return the 
message to a string variable. 


ERR_QUITO 
If passed the error code, will print the 
message on the Error Line and exit frorn 
the program. 
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Exception Handling 


It is also possible to trap interrupts (DEL, CONTROL-C) and quits 
(CONTROL-\) in your INFORMIX·4GL program. The syntax is: 


DEFER \INTERRUPT I QUIT; 


The DEFER keyword means that a global flag (INT_FLAG 
for INTERRUPT, and QUIT_FLAG for QUIT) is set to 
non-zero and may be checked by the programmer. It is the 
programmer's responsibility to reset the flags to zero. The 
default for either an interrupt or a quit is to cause the program 
to stop immediately. 


If the user enters an interrupt during an INPUT or INPUT 
ARRAY statement and you have executed the DEFER 
INTERRUPT statement, the program control leaves the 
INPUT statement and INFORMIX-4GL sets INT 
FLAG. 


You may enter the DEFER INTERRUPT statement only once 
in a program and then only in the MAIN routine. This applies 
to the DEFER QUIT statement as well. 


Data Validation 


You can ensure that data entered through a form conforms to 
appropriate limits or has a permitted value by setting up the 
INCLUDE attribute in the form specification or in the 
syscolval table (see Chapter 3 for a discussion of these con- 
cepts). If your program inserts data into the database from 
sources other than a form, you can check that it meets these 
same restrictions by using the VALIDATE statement. 


VALIDATE 
creates an error if the named variables are not 
consistent with the limitations set for the 
named columns in syscolval. 
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Built-in Functions 


In addition to functions that you create with the FUNCTION 
routine and C functions that you can call, INFORMIX-4GL pro- 
vides a number of built-in functions. You may use the 
following functions In expressions. 


ASCII 
CLIPPED 
COLUMN 
DATE 
DATE( ) 
DAY( ) 
MDY( ) 


MONTH( ) 
SPACES 
TODAY 
USING 
WEEKDAY( ) 
YEAR( ) 


These functions are described in the following sections. There 
are additional functions that can be used only within REPORT 
routines (see Chapter 4 for details). 
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ASCII 


Overview 


INFORMIX·4GL evaluates this function as a single character. 
You can use it to display CONTROL characters. 


Syntax 


ASCII num-expr 


Explanation 


ASCII 


num-expr 


Examples 


is a required keyword. 


is a numeric expression. 


The following DISPLAY statement rings the terminal bell 
(ASCII value of 7). 


DEFINE bell 
CHAR(1) 
LET bell = ASCII 
7 
DISPLAY bell 
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The next REPORT routine fragments show how to implement 
special printer or terminal functions. They assume that, when 
the printer receives the sequence of ASCII characters 9, 11, and 
1, it will start printing in red and, when it receives 9, 11, and 0, 
it will revert to black printing. The values used in the example 
are hypothetical; refer to your printer or terminal manual for 
information on your printer or terminal. 


FORMAT 
FIRST 
PAGE 
HEADER 
LET 
red_on 
= 
ASCII 
9, 
ASCII 
11, 
ASCII 
1 
LET 
red off = ASCII 
9, 
ASCII 
11, 
ASCII 
0 
ON 
EVERY 
RotV 


PRINT 
red_on, 
tty 0 U r 
b i I lis 
0 v e r due . " , 
red off 


Caution! Il"FORMIX·4GL cannot distinguish printable and non- 
printable ASCII characters. Be sure to account for the non-printing 
characters when using the COLUMN function to format your page. 
Since various devices differ in outputting spaces with CONTROL char- 
acters, you may have to use trial and error to line up columns when 
you output CONTROL characters. 
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( 
CLIPPED 


Overview 


CLIPPED displays the character expression that precedes it 
without any trailing blanks. 


Syntax 


char-expr CLIPPED 


Explanation 


char-expr 


CLIPPED 


Notes 


is a required character expression. 


is a required keyword. 


, . 


1. You normally use CLIPPED following a variable name in a 
LET, DISPLAY or PRINT (REPORT routine only) 
statement. 
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Examples 


The following example is from a REPORT routine that prints 
mailing labels. 


FO~AT 


ON EVERY RON 
IF 
(c i t Y IS NOT 
NUL L) 
AND 
(5 tat e 
IS NOT NUL L) 
THEN 
PR INT 
f name CL IPPED, 
1 SPACE, 
Iname 
PRINT company 
PRINT addressl 
IF (address2 
IS NOT NULL) 
THEN 
PRINT address2 
END 
IF 
PRINT city CLIPPED, ", .. 
, state, 
2 SPACES, 
zipcode 
SKIP TO TOP OF PAGE 
END 
IF 
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COLUMN 


Overview 


The COLUMN function returns a string of spaces long enough 
to begin the next item in the designated column. 


Syntax 


COLUMN integer-expr 


Explanation 


COLUMN 


integer-expr 


Notes 


is a required keyword. 


is a required positive integer expression that 
specifies the initial column number of the next 
item to be printed. 


1. In REPORT routines, INFORMIX-4GL calculates the column 
number by adding the number to the left margin you set in 
the OUTPUT section. Otherwise, the column number is 
counted from the left edge of your screen. 


2. If INFORMIX·4GL has already printed past the column 
specified by integer-expr, INFORMIX-4GL ignores the 
COLUMN expression. 


3. If you use the COLUMN function in a DISPLAY state- 
ment, you must specify an integer instead of an integer 
expression after the COLUMN keyword. 
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Examples 


PAGE 
HEADER 
PR I NT 
"NUMBER". 
COLUMN 
12. 
"NAM:t'. 
COlt..lM"ll 35. 
"C I TV" . 


COLUMN 57. 
"ZIP", 
COLLJfd\J 65. 
"PHONE" 
SK I P 
1 LINE 
ON 
EVERY 
RON 


PRINT 
customer_num, 
COLUMN 
12, 
fname 
CLIPPED, 
1 SPACE, 
Iname 
CLIPPED, 
COLUMN 35, 
city 
CLIPPED, 
.. 
state, 


COLUMN 
57, 
z i pcode, 
COLUMN 65, 
phone 
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( 


DATE 


Overview 


The DATE function returns a character string with the value 
of today's date in the format "Thu Sep 20 1986." 


Syntax 


DATE 


Explanation 


DATE 


Examples 


is a required keyword. 


Because DATE returns type CHAR, you can use it with sub- 
scripts to express a day, month, date, or year. The following 
example displays the three-letter abbreviation for the day of 
the week. 


DISPLAY "Today 
is ". 
DATE[1.3] 


Today 
is Mon 
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DATEO 


Overview 


The DATEO function returns a type DATE value correspond- 
ing to the expression with which you call it. 


Syntax 


DATE(expr) 


Explanation 


DATE 


expr 


Examples 


is a required keyword. 


is a required expression that can be converted to a 
type DATE value. 


The following example uses DATE to convert a string to a 
date. 


WiERE 
end_date> DATE("12/13/1986") 


DATE(100) returns the lOOth day after December 31,1899. 
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DAYO 


Overview 


The DAYO function returns the day of the month when you 
call it with a type DATE expression. 


Syntax 


DAY(date-exp) 


Explanation 


DAY 


date-exp 


is a required keyword. 


is a required expression of type DATE. 
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MDYO 


Overview 


The MDYO function returns a type DATE value when you call 
it with three expressions that evaluate to integers representing 
the month, date, and year. 


Syntax 


MDY(exprJ, expr2, expr3) 


Explanation 


MDY 


exprl 


expr2 


expr3 


Notes 


is a required keyword. 


is an expression that evaluates to an integer 
representing the number of the month (1-12). 


is an expression that evaluates to an integer 
representing the number of the day of the 
month (1-28,29,30, or 31, depending on the 
month). 


is an expression that evaluates to a four-digit 
integer representing the year. 


1. The value of expr3 cannot be the abbreviation for the year. 
For example, 84 is in the first century. 
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MONTHO 


Overview 


The MONTHO function returns an integer corresponding to its 
type DATE argument. 


Syntax 


MONTH(date-expr) 


Explanation 


MONTH 


date-expr 


is a required keyword. 


is a required expression of type DATE. 
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SPACES 


Overview 


This function is used only within reports to return a string of 
spaces. It is identical to a quoted string of spaces. 


Syntax 


num-expr SPACErS] 


Explanation 


num-expr 


SPACES 


Notes 


is a numeric expression. 


is a required keyword. You can use the key- 
word SPACE in place of SPACES if you like. 


1. You can only use the SPACES function in PRINT state- 
ments that appear in REPORT routines. (See Chapter 4 
for more information about PRINT.) 


Examples 


The following example is from a mailing label report. 


FORMAT 
ON EVERY RON 
PR INT 
f name, 
In ame 
PRINT company 
PRINT address1 
PRINT address2 
PRINT city, ", 
" 
, state, 
2 SPACES, 
zipcode 
SKIP 
2 LINES 
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TODAY 


Overview 


TODAY evaluates as type DATE with a value of today's date 
as supplied by the operating system. 


Syntax 


TODAY 


Explanation 


TODAY 


Examples 


is a required keyword. 


The following example is from a REPORT routine. 


SKIP 
1 LINE 
PRINT 
COLUM\! 
15. 
"FRCM: 
". 
begin_da1e 
USING 
"rrrn 
dd 
yy", 
COLUMN 
35. 
"TO: 
t" 
end_dale 
USING "rml/dd 
yytt 
PRINT 
COLlIM'J 
15. 
"Report 
run 
date; 
TODAY USING "rmrn dd. 
yyyy" 


SKIP 2 LINES 
PRINT COLUM< 2. 
"ORDER DATE". 
COLUMN 15. 
"CCMPANY". 


COLUMN 35. 
"NAME". 
COLlJt,fol 57. 
"NUMBER". 
COLUMN 65. 
"AMOUNT" 
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USING 


Overview 


The USING function allows you to format a numeric or date 
expression. With a numeric expression, you can use USING to 
line up decimal points, right- or left-justify numbers, put nega- 
tive numbers in parentheses, and perform other formatting 
functions. With a date expression, USING will convert the 
date to a variety of formats. 


Syntax 


expr1 LTSING expr2 


Explanation 


exprl 


USING 


expr2 


is the required expression that specifies what 
USING is to format. 


is a required keyword. 


is the required format string that specifies how 
USING is to format expr1. Refer to "Notes" 
later in this section. 


Formatting Numeric Expressions. 
The format string consists of 
combinations ofthe following characters: * & # < , . - + ( ) $. 
The characters - + ( ) $ will float. When a character floats, 
INFORMIX-4GL displays multiple leading occurrences of the char- 
acter as a single character as far to the right as possible, 
without interfering with the number that is being displayed. 
Refer to the following list for an explanation of these 
characters. 


* 
This character fills with asterisks any positions in the 
display field that would otherwise be blank. 
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& This character fills with zeros any positions in the display 
field that would otherwise be blank. 


# 
This character does not change any blank positions in the 
display field. You can use this character to specify a 
maximum width for a fielg. 


< This character causes the numbers in the display field to be 


left-justified. 


This character is a literal; USING displays it as a comma. 
USING will not display a comma unless there is a number 
to the left of it. 


This character is a literal; USING displays it as a period. 
You can only have one period in a format string. 


This character is a literal; USING displays it as a minus 
sign when expr1 is less than zero. When you group several 
minus signs in a row, a single minus sign floats to the right- 
most position without interfering with the number being 
printed. 


+ This character is a literal; USING displays it as a plus sign 
when exprl is greater than or equal to zero and as a minus 
sign when it is less than zero. When you group several plus 
signs in a row, a single plus sign floats to the rightmost 
position \\'ithout interfering with the number being printed. 


This character is a literal; USING displays it as a left 
parenthesis before a negative number. It is the accounting 
parenthesis that is used in place of a minus sign to indicate 
a negative number. When you group several parentheses in 
a row. a single left parenthesis floats to the rightmostposi- 
tion without interfering with the number being printed. 


This is the accounting parenthesis that is used in place of a 
minus sign to indicate a negative number. One of these 
characters generally closes a format string that begins with 
a left parenthesis. 
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$ 
This character is a literal; USING displays it as a dollar 
sign. When you group several dollar signs in a row, a single 
dollar sign floats to the rightmost position without interfer- 
ing with the number being printed. 


Refer to the "Examples" section for examples of formatting 
numeric expressions. 


Formatting Date Expressions. 
The format string consists 
of combinations of the characters m, d, and y, as shown in 
Figure 1-1. Refer to the "Examples" section for examples 
of formatting date expressions. 


dd 


ddd 


mm 
mmm 


':,y 
'yyyy 


day of the month as a 2-digit 
number (01-31) 
dav of the week as a 3-1etter 
abbreviation (Sun through Sat) 


month as a 2-digit number (01-12) 
month as a 3-1etter abbreviation 
(Jan through Dec) 


year as a 2-digit number in the 1900s (00-99) 
year as a 4-digit number (0001-9999) 


Figure 1-1. Combinations of Date Format Strings 


Notes 


1. The format string must appear between quotation marks. 


2. Although USING is generally used as part of a DISPLAY or 
PRINT statement, you can also use it with LET. 


3. If you attempt to display a number that is too large for a 
display field, INFORMIX-4GL will fill the field with asterisks to 
indicate an overflow. 
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Examples 


The example below prints the balance field using a format 
string that allows up to $9,999,999.99 to be formatted correctly. 


DISPLAY "The current 
balance 
is ", 
23485.23 
USING "$#,###,##&.&&" 


The result of executing this DISPLAY statement with the 
value 23,485.23 is shown below. 


The current 
balance 
is 
$ 
23,485.23 


This example fixes the dollar sign. If dollar signs were used 
instead of # characters, the dollar sign would have floated with 
the size of the number. The example also uses a mix of # and 
& fill characters. The # character provides blank fill for unused 
character positions, while the & character provides zero filling. 
This format ensures that, even if the number is zero, the posi- 
tions marked with &s will appear as zeros, not blanks. 


The following example is from a REPORT routine. 


ON 
LAST 
RON 


SKIP 
2 
LINES 
PRINT 
"Number 
of 
customers 
in" 
state," are" 
COUNT ( .) 
US I NG "««<,, 


PAGE 
TRAILER 
PRINT 
COLUMN 
35, 
"page ", 
PAGE NO USING "««,, 
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The following example is from a complex REPORT routine and 
illustrates several different formats. 


SKIP 
1 LINE 
PRINT 
COLUM-< 
15, 
"FRCJ.1: 
begin_date. USING "mm!dd!yy", 


COLUtM 35, 
"TO: 
", end_date USING "mm:dd:yy" 
PRINT 
COLl..Ifo.It'.l 
15, 
"Report 
run 
date: 
TODAY USING 
"mmm dd, 
yyyy" 
skip21ines 
PRINT COLUtM 2, 
"ORDER DATE", 
COLlJt,fol 
15, 
"CCJ.1PANY" , 


COLUMN 35, 
"NAME", 
COLUMN 57, 
"NUMBER", 
COLlJt,fol 65, 
"AMOUNT" 


BEFORE GROUP OF days 
SKIP 2 LINES 


AFTER GROUP OF 
number 
PRINT COLUMN 2, 
order_date, 
COLUMN 15, 
company CLIPPED, 


COLUMN 35, 
f name CLI PPED, 
1 SPACE, 
Iname CLI PPED, 


COLUM-< 55, 
number 
USING "####" , 


COLUM-< 60, 
GROUP SUM (total-price) 


USING 
"$$.$$$,$$$.&&" 


AFTER GROUP OF days 
SK IP 1 LINE 
PRINT 
COLlJM'.J 
21, 
"Total 
amoul"!t 
ordered 
for 
the 
day 
GROUP SUM (total-price) 
USING "$$$$.$$$,$$$.&&" 
SKIP 
1 LINE 
PR INT 
COLUMN 
15, 


ON LAST 
RON 


SKIP 
1 LINE 
PRINT 
COLUM-< 15. 


SKIP 2 LINES 
PRINT 
"Total 
Amount 
of 
orders: 
USING "$$$$,$$$,$$$.&&" 
SUM (t 0 I al-p rice) 


PAGE 
TRA ILER 
PRINT 
COLUM-< 28, 
PAGENO USING "page ««" 
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The displays on the next four pages illustrate the full power of 
the USING function. 


Format 
Numeric 
Formatted 
String 
Value 
Result 


"#####" 
0 
bbbbb 
"&&&&&" 
0 
00000 
"$$$$$" 
0 
bbbb$ 
" .... -- .... " 
0 


"««<" 
0 
(n u I I 
string) 


"##,###" 
12345 
12,345 
"##,###" 
1234 
b 1,234 
"##,###" 
123 
bbb123 
"##,###" 
12 
bbbb12 
"##,###" 
1 
bbbbb1 
"##,###" 
-1 
bbbbb1 
"##,###" 
0 
bbbbbb 


"&&,&&&" 
12345 
12,345 
"&&,&&&" 
1234 
01,234 
"&&,&&&" 
123 
000123 
"&&,&&&" 
12 
000012 
"&&,&&&" 
1 
000001 
"&&,&&&" 
0 
000000 


"$$,$$$" 
12345 
............ 
(overflow) 
"$$,$$$" 
1234 
$1 ,234 
"$$,$SS" 
123 
bb$123 
"$$,$$$" 
12 
bbb$12 
"$$,$$$" 
1 
bbbb$1 
"$$,$$$" 
0 
bbbbb$ 


" .. 
...... tt 
12345 
12,345 
"" .. 
...... " 
1234 
• 1,234 
"" .. 
.. 
", .. " 
123 
••• 12 3 
" .... 
...... " 
12 
.. ...... 1 2 
" .... 
...... " 
1 
.. ........ 1 
" .. '" 
...... tt 
0 
............ 
, 


This table uses the character b to represent 
a blank or space. 
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Format 
Numeric 
Formatted 
String 
Value 
Result 


"##,###.##" 
12345.67 
12,345.67 
"##,###.##" 
1234.56 
b1,234.56 
"##,###.##" 
123.45 
bbb123.45 
"##,###.##" 
12.34 
bbbb12.34 
"##,###.##" 
1 . 23 
bbbbb 1.23 
"##,###.##" 
O. 12 
bbbbbO.12 
"##,###.##" 
0.01 
bbbbbb.01 
"##,###.##" 
-0.01 
bbbbbb.01 


"&&,&&&.&&" 
12345.67 
12,345.67 
"&&,&&&.&&" 
1234.56 
01,234.56 
"&&,&&&.&&" 
123.45 
000123.45 
"&&,&&&.&&" 
0.01 
000000.01 


"$$,$$$.$S" 
12345.67 
.................. 
(over! low) 
"$$,$$$.$$" 
1234.56 
$1,234.56 
"$$,$$$.##" 
0.00 
$.00 
"$S,$$$.##" 
1234.00 
$'1,234.00 
"$$,$$$.&&" 
0.00 
$.00 
"$$,$$$.&&" 
1234.00 
$1,234.00 


"-##,###.##" 
-12345.67 
-12,345.67 
"-##,###.##" 
-123.45 
-bbb123.45 
"-##,###.##" 
-12.34 
-bbbb12.34 
"-#,###.##" 
-12.34 
-bbb12.34 
"-,###.##" 
-12.34 
-bb12.34 
"-,-##.##" 
-12.34 
-12.34 
"--,-#.##" 
-1.00 
-1.00 


"-##,###.##" 
12345.67 
12,345.67 
"-##, ###. ##" 
1234.56 
1,234.56 
"-##,###.##" 
123.45 
123.45 
"-##,###.##" 
12.34 
12.34 
"-#, ###. ##" 
12.34 
12.34 
"-,###.##" 
12.34 
12.34 
"--,-##.##" 
12.34 
12.34 
"--,--.##" 
1 . 00 
1 . 00 
----- 
-.01 
-.01 
, 
. 


This table uses the character b to represent 
a blank or space. 
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Format 
Numeric 
Formatted 
String 
Value 
Result 


"--,--.&&" 
-.01 
-.01 
"-$$$,$$$.&&" 
-12345.67 
-$12,345.67 
"-$$$,$$$.&&" 
-1234.56 
-b$1,234.56 
"-$$$,$$$.&&" 
-123.45 
-bbb$123.45 
" -$$,$$$.&&" 
-12345.67 
-$12,345.67 
! 


"-$$,$$$.&&" 
-1234.56 
-$1,234.56 
"-$$,$$$.&&" 
-123.45 
-bb$123.45 
"-$$,$$$.&&" 
-12.34 
-bbb$12.34 
"-$$,$$$.&&" 
-1.23 
-bbbb$1.23 


"--,-$.&&" 
-12345.67 
-$12,345.67 
"--,-$.&&" 
-1234.56 
-$1,234.56 
"--,-$.&&" 
-123.45 
-$123.45 
"--,-$.&&" 
-12.34 
-$12.34 
"--,-$.&&" 
-1.23 
-$1.23 
"--,-$.&&" 
-.12 
-$.12 


"$' .... 
I 
...... 
• &&" 
12345.67 
$'12,345.67 
"$""" ,"" ... &-&" 
1234.56 
$"1,234.56 
"$" .... 
I 
...... 
• &&" 
123.45 
$ .... 123.45 


"$ ......, ....... && 
tt 
12.34 
$·····12.34 
"$" .... 
I 
.... 
' 
.• &&" 
1 . 23 
$ •••••• 1 . 23 
"$""" 
I 
...... 
• &&" 
. 12 
$" ............ . 12 


"($$$,$$$.&&)" -12345.67 
($12,345.67) 
"($$$.$$$.&&)" 
-1234.56 
( 
$1,234.56) 
"($$$,$$$.&&)" 
-123.45 
( 
$123.45) 
"«$S,$$$.&&)" -12345.67 
($12,345.67) 
"({$$,$$$.&&)" 
-1234.56 
($1,234.56) 
"({$$,$$$.&&)" 
-123.45 
( 
$123.45) 
"({$$,$$$.&&)" 
-12.34 
( 
$12.34) 
"({$$,$$S.&&)" 
-1.23 
( 
S 1 .23) 


" { { { { , { ($ . && ) " -12345.67 
($12,345.67) 
" { { { { , { ($ . && ) " 
-1234.56 
($1,234.56) 
"{{{{, ({$.&&)" 
-123.45 
($123.45) 
" ( ( ( ( , « $ . && ) " 
-12.34 
($12.34) 
"««,«$.&&)" 
-1.23 
($1.23) 
" ( ( ( ( , ( ( $ . && ) " 
-.12 
($ . 12) 
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Format 
Numeric 
Formatted 
String 
Value 
Result 


"($$$,$$$.&&)" 
12345.67 
$12,345.67 
"($$$,$$$.&&)" 
1234.56 
$1,234.56 
"($$$,$$$.&&)" 
123.45 
$123.45 
"«$$,$$$.&&)" 
12345.67 
$12,345.67 
"«$$,$$$.&&)" 
1234.56 
$1,234.56 
"«$$,$$$.&&)" 
123.45 
$123.45 
"«$$,$$$.&&)" 
12.34 
$12.34 
"«$$,$$$.&&)" 
1 . 23 
$1.23 


"««, «$.&&)" 
12345.67 
$12,345.67 
" ( ( ( (, ( ($ . && ) " 
1234.56 
$1,234.56 
"««,«$.&&)" 
123.45 
$123.45 


" ( ( ( ( , ( ($ . && ) " 
12.34 
$12.34 
"««, «$.&&)" 
1 . 23 
$1.23 
" ( ( ( ( , ( ($ . && ) " 
. 12 
$ .12 


"«<,«<" 
12345 
12,345 
"«<, «<" 
1234 
1 . 234 
"«<,«<" 
123 
123 
"«<,«<" 
12 
12 


The following examples show sample conversions for 
December 25, 1986. 


Format String 


"mmddyy" 
"ddmmyy" 
"yymmdd" 
"yy /mm/ dd" 
"yy 
mm dd" 


"yy-mm--dd" 
"mmm. 
dd, 
yyyy" 
"mmm dd 
yyyy" 
"yyyy 
dd 
mm" 
"mmm dd 
yyyy" 
"ddd, 
mmm. 
dd, 
yyyy" 
"(ddd) 
mmm. 
dd, 
yyyy" 
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Formatted Result 


122586 
251286 
861225 
86/12/25 
86 
12 
25 
86-12-25 
Dec. 
25, 
1986 
Dec 
25 
1986 
1986 25 
12 
Dec 
25 
1986 
Thu, 
Dec. 
25, 
1986 
(Thu) 
Dec. 
25, 
1986 


'i 


WEEKDAYO 


Overview 


The WEEKDAYO function returns an integer that represents 
the day of the week when you call it with a type DATE 
expression. 


Syntax 


WEEKDAY(date-expr) 


Explanation 


I: 


WEEKDAY 


date-expr 


Notes 


is a required keyword. 


is a required expression of type DATE. 


1. WEEKDAY returns an integer in the range 0-6. 
Zero represents Sunday, 1 represents Monday, and so on. 
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YEARO 


Overview 


The YEARO function returns an integer that represents the 
year (four digits for 1986) when you call it with a type DATE 
expression. 


Syntax 


YEARidate-expr) 


Explanation 


YEAR 


date-expr 
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is a required keyword. 


is a required expression of type DATE. 


C Functions 


INFORMIX-4GL programs can call C language functions. To pro- 
vide a transparent function calling mechanism, INFORMIX-4GL 
requires that C functions follow a calling convention that allows 
data to be passed between the INFORMIX-4GL program and the C 
function. 


The convention utilizes a stack, which is a data structure that 
can be accessed in a pre-defined way by both INFORMIX-4GL pro- 
grams and C functions. The operations on a stack are either to 
add a variable to the stack, "push," or to retrieve a variable 
from the stack, "pop." 
The stack acts as a Last-In First-Out 
queue, so that the last variable added to the stack is the next 
variable to be removed from the stack if you do a pop. 


Consider the following INFORMIX-4GL statement: 


CALL myfunc (a,b,c) 


Part of the calling convention is that function arguments are 
pushed from left to right onto the stack. INFORMIX-4GL 
automatically pushes the variables a, b, and c onto the stack, 
in that order. Another part of the calling convention requires 
INFORMIX-4GL to automatically pass the number of calling 
parameters as the only real argument to the function. 
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The C function designed to work with INFORMIX-4GL must obey 
the calling convention by complementing the actions of 
INFORMIX-4GL. All compatible C functions have only one argu- 
ment' which is the number of parameters that INFORMIX-4GL 
placed on the stack. You use this argument to pop the calling 
parameters. INFORMIX-4GL supplies a number of library func- 
tions to assist this process. The library functions are identified 
as follows: 


Data Definition 
Popping Functions 
Pushing Functions 


int 
i; 
popint(&i) 
retint(i) 
short 
s' 
popshort(&s) 
retshort(s) 
, 
long 
I· 
poplong(&I) 
retlong(l) 
, 
float 
f; 
popflo(&f) 
retflo(&f) 
double 
d· 
popdub(&d) 
retdub(&d) 
, 
char 
str[m]; 
popquote(str, m) 
retquote(str) 
dec- t 
dm; 
popdec(&dm) 
retdec(&dm) 


Your first step in a C function is to pop all the arguments in 
the reverse order from the order in the call. If the call is to 
myfunc, you must first pop c, and then b, and, finally, a. You 
must use the library function that is appropriate for the data 
type of the calling argument. Unless you pop all the argu- 
ments, the stack becomes corrupted, and your INFORMIX-4GL 
program can produce unpredictable results. 


To return values from the C function to the INFORMIX-4GL 
program, you must push the values onto the stack. They must 
be pushed in the same order as they appear in the RETURN- 
ING clause of your INFORMIX-4GL statement. For example, if 
the statement is 


CALL ... 
RETURNING x, 
y 


you must push x before pushing y within your C function. 
You must use the library function that matches the data type 
to execute the push. The last statement that your C function 
executes must be a return where the only parameter is the 
number of variables that are being returned. Make sure that 
the variables returned by your C function match, in both 
number and data type, the arguments in the RETURNING 
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clause of your INFORMIX-4GL statement. If you do not return 
the correct data types, your program can execute unpredictably. 
Failure to return the expected number of arguments causes an 
error. 


When using the C library functions, you must be aware of the 
following factors: 


• 
If you use the retquote(str) function, you must null- 
terminate the string. 


• 
The string str in popquote will be null-terminated; you 
should allow for that in the value of m. 


• 
The dec_t structure is defined in Appendix K, along with a 
number of useful functions that you can use to convert 
DECIMAL variables to other numeric data types and back 
again within your C functions. (They are not necessary 
within an INFORMIX-4GL program since the functionality is 
alreadv built into INFORMIX-4GL.) 
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Examples 


The first example shows the basic structure for C functions 
that you call from an INFORMIX-4GL program. 


myfunc(n) 
int 
n; 


/* 
n specifies how many 
4g1 
parameters 


* 
came 
i n 


* / 


test 
that 
the value 
of 
n is correct 


pop 
n 4g1 
parameters 
in 
reverse order, 
right 
to 
left 


. .. 
code 


push 
x return 
4g1 
parameters 
left 
to 
right 


return(x) 
/* 
must 
return 
the 
number 
x of 
4g1 


* 
"RETURN I NG" 


* / 


The following INFORMIX-4GL program CALLs the C language 
function sndmsg, which converts a string into EBCDIC and 
sends it to a remote computer. Two arguments are explicitly 
passed to the function: the source string and its length. 
INFORMIX-4GL automatically passes the number ofarguments to 
the function. 
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MAIN 


DEFINE charlype CHAR(BO). 
ms 9 _5 tat us 
I NTEGE R. 


ret-~rn_Code 
INTEGER 


LET 
char type = tI234" 


# 
s n dms 9 
r e qui res 
two 
8 r 9 urne n t S 
8 n d 
ret urn.s 
two 
8 r g ume n I 5 . 


# 
~s 
def ined 
by 
the 
C 
langu8ge 
funCI ion. 


~ 
You 
must 
ensure 
that 
the 
order 
and 
data 
types 
of 
at r 
a r 9 urne n I 5 
are 
c amp at i b I e 
bet we e nth e 
4 9 I 
C8 [ I 
I n 9 


:/1 
program 
and 
the 
called 
functIon 


CALL 
sndmsg(chartype, 
4) 
RETURNING 
mSLstatus, 
return_code 


IF 
return_code <> 0 
THEN 


DISPLAY 
tiEr ror 
code: 
tI 
ret urn_code 


END 
IF 


DISPLAY msg_status 


END MA IN 


The function sndmsg checks that the correct number of argu- 
ments are passed. INFORMIX-4GL cannot guarantee recovery of 
the stack if a function is called with the wrong number of argu- 
ments, since that is a failure to follow the calling convention 
between INFORMIX-4GL and C functions. sndmsg aborts the 
program if the wrong number of arguments is passed. 


If the correct number of arguments is passed, sndmsg pops 
the arguments from the stack, using the library functions 
appropriate for the data type. 
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#include "stdio 
hit 
itinclude "decima: 
h" 
sndmsg(nargs) 


.,. 
4g1 
syntax 
is 
CALL 
sndmsg 
(input,len) 
RETURNING 
msg_number, 
retcode·' 


int 
nargs; 
i" 
4g1 
passes 
the 
number 
of 
arguments 
8S 
an 
integer 
., 


char 
in t 
in I 


input;aO·: 
ms g_" umbe r ; 
len, 
retcode; 


," 
4g1 
and 
C 
funcI ion must 
agree 
on 
data 
/. 
types 
and 
the 
order 
that 
arguments 
are 
j" 
placed 
on 
the 
stack 
"/ 


!. 
Check 
that 
the 
cor rect 
number 
of 
arguments are passed·! 


if 
(nargs 
!= 2) 


fprlntl 
(stderr, 
"s n dms 9 : 
w ron 9 
numb e r 
0 far 9 ume n t s") ; 


exit(l); 
,. 
No 
recovery 
from 
this 
error 
.; 


• 
Pop 
rig h t mo s tar 9 urne n I 


popin! (&Ien): 


• 
Pop 
next 
argument 
., 


POPQuote( inpur, len); 


/. 
Finished with 
function 
calling 
convention 
./ 


• 
Start 
funct ion 
processing 
., 


msg 
number =-1; 
reteode = cvtebcd 
(&input, 
len): 
/" 
user-written 
function 
.. 


if 
(retcode!= 0) 
msg_number = sndrmt 
(input,len); 
/. 
user-written 
function 
.. 


(. 
Finished 
processing 
"i 
• 
Return 
(push) 
leftmost 
argument 
", 


ret i nt (msQ_.number): 


,. 
Return 
next 
argument 
"/ 


ret int (retcode): 


,. 
Fin ish ed 
ret urn i ngar g urne n t s ., 


I· 
Re t urn 
from 
fun c t i 0" 
9 i v i n 9 
numb e r 
0 far g urne n t s 
.. / 


ret urn (2) ; 


To return values to the INFORMIX·4GL program, the C function 
uses the appropriate push functions for the data type and 
pushes return arguments onto the stack from left to right. The 
last statement executed by the function returns the number of 
arguments, which is two for sndmsg. A discrepancy between 
the number of return arguments in the function and the 
number of arguments expected by the INFORMIX-4GL program 
results in an error. 
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Compiling and Executing Programs 


This section describes how to compile your INFORMIX·4GL 
program from the operating system level. You may prefer to 
write and compile your program within the INFORMIX-4GL 
Programmer's Environment. (See Chapter 6 for a description 
of the Programmer's Environment.) 


To convert the INFORMIX-4GL code that you write into an 
executable program, four steps are necessary: 


1. Preprocess the INFORMIX·4GL code to produce INFORMIX· 
ESQL/C code. 


2. Preprocess the INFORMIX-ESQLlC code to produce C language 
code. 


3. Compile the C code with the C compiler to create an 
object file. 


4. Link the object file with the INFORMIX-ESQLlC libraries, as 
well as your own. 


You can use the c4g1 command file that is installed with 
I1'o'FORMIX·4GL to perform all these tasks. 


To preprocess and compile an INFORMIX·4GL program, give the 
source module name the extension .4g1 and enter the following 
command in response to your system prompt: 


c4g1 
[-e][-a][-otherargs 
... ][-0 
out file] 
\ 
source.4gl 
[otheresql.ec 
... ] 
\ 
[othersrc.c 
] 
\ 
[otherobj.o 
][-Iyour lib ... ] 


Explanation 


-e 
allows you to request just the preprocessor 
steps with no compilation or linking. 
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-a 
causes your compiled program to check array 
bounds at runtime. The -a option must 
appear on the command line before the 
source.4g1 filename. 


otherargs 
are other arguments that you want to pass 
to the C compiler. 


outfile 
is the name of the executable output file. 


source.4g1 
is the name of your INFORMIX-4GL source 
module. 


otheresql.ec 
is an INFORMIX-ESQL/C source file that you 
want to compile and link. 


othersrc.c 
is a C language source file that you want to 
compile and link. 


otherobj.o 
is an object file that you want to link with 
your INFORMIX-4GL program. 


yourlib 
is a library that you want to extract functions 
from (for example, libm.a for mathematical 
functions). 


Notes 


1. If you are using a DOS system on MS-NET, you will not 
be able to compile INFORMIX-4GL programs, link files, or use 
a c4g1 command file while you are on the net. This is due 
to the memory requirements of the MS-NET software. 
To compile an INFORMIX-4GL program, you need to have 
available 640K of memory. 


To ensure that you have sufficient memory available to 
compile your programs, first exit the network. Then com- 
pile and link the programs from within the Programmer's 
Environment or using c4gl. You can then reenter the 
network to run your programs. 
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2. Since the -a option requires additional processing, you 
may want to use this option only during development for 
debugging purposes. 


3. c4g1 passes all C arguments (-otherargs) and other 
C source and object files (othersrc.c and otherobj.o) 
directly to the C compiler cc. 


4. If there is no MAIN statement in sourceAgI, your code 
will be compiled to source.o, but will not be linked with 
other routines or the libraries. You can link it with a main 
routine at another time. In this way, you can compile 
INFORMIX·4GL modules separately from your MAIN module. 


Examples 


The simplest case is to compile a single-module INFORMIX·4GL 
program: 


c4g1 
single.4gl -0 single 


If modl.o, mod2.o, and mod3.o are previously compiled 
INFORMIX·4GL modules and you want to compile and link 
mod4 AgI to create the executable program myappl, use 
the following command line: 


c4g1 
mod1.0 mod2.0 mod3.0 mod4.4gl -0 myappl 
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Program Filename Extensions 


The source, executable, object, error, and backup files generated 
by INFORMIX-4GL are stored in the current directory and are 
labeled with a filename extension. The list below shows the file 
extensions for the source, executable, object, and error files. 
These files are produced during the normal course of using 
INFORMIX-4GL. The backup files appear in a later list. 


fileAgI 
is an INFORMIX-4GL source file. 


file.o 
is an INFORMIX-4GL object file. 


fileAge 
is an Il'.TFORMIX·4GL executable (runable) file. 


file.err 
is an INFORMIX·4GL source error file, created when 
an attempt to compile a module or form specifica- 
tion fails. The file contains INFORMIX-4GL source 
code plus compiler syntax errors. 


file.ec 
is an intermediate source file, created during the 
normal course of compiling an INFORMIX-4GL 
module. 


file.c 
is an intermediate C file, created during the 
normal course of compiling an INFORMIX·4GL 
module. 


form.per 
is a FORM4GL form source file. 


form.frm 
is a FORM4GL form object file. 


The following list contains the INFORMIX·4GL backup files: 


fileAbl 


file.4bo 


is an INFORMIX·4GL source backup file, created 
during the modification and compilation of a 
program module. 


is an INFORMIX·4GL object backup file, created 
during the modification and compilation of a 
program module. 
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file.4be 


file.ere 


file.pbr 


file.ibm 


is an INFORMIX-4GL executable backup file, created 
during the modification and compilation of a 
program module. 


is an INFORMIX-4GL object and/or executable error 
file, created when an attempt to compile a non- 
INFORMIX-4GL module fails or during the linking 
phase of the compilation. The file contains 
INFORMIX-4GL source code plus annotated compiler 
errors. 


is a FORM4GL form source backup file. 


is a FORM4GL form object backup file. 


Under normal conditions, INFORMIX-4GL creates the backup and 
intermediate files as necessary and deletes them upon a suc- 
cessful compilation. If you interrupt a compilation, you may 
find one or more of the files in your current directory. 


The file.4bl source backup file contains a copy of the fileAgI 
source file. During the compilation process, INFORMIX-4GL 
modifies the (original) file.4g1 source file. In the event of a 
system crash, you may need to replace the modified file.4g1 
file with the backup copy contained in the fileAbl file. 
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Chapter Overview 


Relational Database Systems, Inc., (RDS) has developed RDSQL 
as an extension of the Structured Query Language (SQL) 
developed by IBM. The RDS additions to the language permit 
you to change databases, change the names of tables and 
columns, and increase the functionality of ANSI standard SQL 
statements. In the family of RDS database products, RDSQL 
plays several roles. In INFORMIX-SQL, RDSQL is both the inter- 
active query language and the language you use to choose the 
data for ACE, the INFORMIX-SQL report-writing program. 
Read about these uses of RDSQL in the INFORMIX-SQL User 
Manual. In INFORMIX-ESQLlC, RDSQL is the database query 
language that you embed in C programs to create an applica- 
tion. In INFOR!\IIX-4GL, RDSQL statements are combined with 
those described in Chapter 1 to form an almost seamless 
fourth-generation language. 


This chapter describes RDSQL and gi\les an overviev,; of its 
statements. The full syntax and rules governing RDSQL 
statements are located in Chapter 7 of the INFORMIX-4GL 
Reference Manual. 
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Relational Databases 


The statements ofRDsQL create and manipulate relational 
databases. A relational database consists of one or more tables 
that, in turn, are constructed of rows and columns. Each row 
contains a particular set of column values. Databases are 
created as subdirectories of the current directory. The name of 
the directory is the database name with the extension .dbs. 
The database subdirectory contains nine system catalog tables 
that define the database dictionary. It also contains the tables 
that constitute the database. Each of these tables is repre- 
sented by data files and index files with the extensions .dat 
and .idx, respectively. The system catalogs are described in 
Appendix B. 


RDSQL Identifiers 


An RDSQL identifi·er is the name of an object and can consist of 
letters, numbers, and underscores (_). The first character 
must be a letter. Unless qualified to the contrary. an identifier 
can have from one to eighteen characters. 


Database 
A database name is an identifier that can have 
from one to ten (UNIX) or eight (DOS) 
characters. 


Table 
A table name is an identifier that must be unique 
within the database. 


Column 
A column name is an identifier that must be 
unique within a table; there can be duplicate 
column names within a database. When column 
names within different tables are not unique, use 
the notation table.column to specify the intended 
column. If you intend to define an INFORMIX-4GL 
record like a table, the first eight characters of 
each column name in the table must be unique 
within the table. 
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If there is an ambiguity because an INFORMIX-4GL identifier and 
an RDSQL identifier are the same, INFORMIX-4GL assumes that 
the INFORMIX-4GL identifier refers to a program variable and 
not to the RDSQL object. If you want to override this default 
assignment, prefix the RDSQL identifier with an @ sign. For 
example, if lname is defined as a program variable and you 
wish to refer to the database column of the same name, use 
@lname for the column name: 


SELECT @Iname 
INTO 
Iname 
FROM customer 


Database Data Types 


You must assign a data type to every column in the database 
(see the CREATE TABLE statement in Chapter 7). With the 
exception of the SERIAL data type, the definitions of the data 
types here are identical with the definitions of the same types 
in Chapter 1. Following are the valid RDSQL data types: 


CHAR(n) 
is a character string of length n (where 
1 <= n <= 32,767). 


SMALLINT 
is a whole number from -32,767 to 
+32,767. 


INTEGER 
is a whole number from -2,147,483,647 
to +2,147,483,647. 


DECIMAL[(m[,n])] 
is a decimal floating-point number with a 
total of m «= 32) significant digits (the 
precision) and n « = m) digits to the 
right of the decimal point (the scale). 
When you give values for both m and n, 
the decimal variable has fixed-point 
arithmetic. All numbers less than 0.5 X 
lO-n in absolute value have the value 
zero. The largest absolute value of a 
variable of this type that can be stored 
without an error is lOm-n _ lO-n. 
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SMALLFLOAT 


FLOAT 


MONEY[(m[,n])] 
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The second parameter is optional and, 
if missing, the variable is treated as a 
floating decimal. This means that 
DECIMAL(m) variables have a precision 
of m and a range in absolute value from 
-128 
126 
10 
to 10 
. If no parameters are 
designated, DECIMAL is treated as 
DECIMAL(16), a floating decimal. 


is a binary floating-point number 
corresponding to the single-precision, 
floating-point data type. The range of 
values for a SMALLFLOAT data t}'Pe is 
the same as the range of values for the 
"float" data type in the C language on 
your machine. On some small machines, 
RDSQL implements SMALLFLOAT as 
DECIMAL(8). See the "Small Machine 
Features" note that follows. 


is a binary floating-point number 
corresponding to the double-precision, 
floating-point data type. The range of 
values for a FLOAT data t}'Pe is the 
same as the range of values for the "dou- 
ble" data type in the C language on your 
machine. On some small machines, 
RDSQL implements FLOAT as DECI- 
MAL(l6). See the "Small Machine 
Features" note that follows. 


can also take two parameters like the 
DECIMAL data type. The limitation on 
values for columns of type MONEY(m, 
n) is the same as for columns of type 
DECIMAL(m, n). The type MONEY(m) 
is defined as DECIMAL(m, 2) and, if no 
parameter is given, MONEY is taken to 
be DECIMAL(l6, 2). Regardless of the 


SERIAL[(n)] 


DATE 


number of parameters, the data type 
MONEY is always treated as a fixed 
decimal number. 


is a unique sequential integer assigned 
automatically by RDSQL. You can assign 
an initial value n. The default starting 
integer is 1. 


is a date entered as a character string in 
one of the formats described in Chapter 1 
and stored as an integer number of days 
since December 31, 1899. 


Small Machine Features: On some small machines, 
SMALLFLOAT and FLOAT columns are implemented as DECI- 
MAL(8) and DECIMAL(l6), respectively. If you are not sure 
whether your computer falls into the "small machine" category, you 
can create a table with a SMALLFLOAT or FLOAT column and 
then query the syscolumns table for the data type of the column. 
(See the appendix "System Catalogs" for more information about 
the syscolumns table.) 


If you have a small machine, the automaticconversion of 
SMALLFLOAT and FLOAT data types to DECIMAL data type 
occurs when you create or modify a table. Although INFORMIX-4GL 
does not change the data definition in your CREATE TABLE or 
ALTER TABLE statement, it records the column data type as DEC- 
1MAL in the database, treats SMALLFLOAT and FLOAT numbers 
as DECIMAL numbers, and stores column data as DECIMAL(8) or 
DECIMAL(l6). You may find it easier to define SMALLFLOAT 
and FLOAT columns as DECIMAL columns so that your CREATE 
TABLE statement reflects the table structure stored in the database. 
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RDSQL Statement Summary 


Six different types of RDSQL statements are used with 
INFORMIX-4GL: 


• 
Data definition 
• 
Data manipulation 
• 
Data access 
• 
Cursor management 
• 
Data integrity 
• 
Dynamic management 


Data Definition 


Data definition statements include those that create and drop a 
database and its tables, views, and indexes, modify tables, 
indexes. and columns, or rename tables and columns. Of this 
list, only the DATABASE statement is required before manipu- 
lating the data of an existing database or defining program 
variables LIKE columns in the database. 


CREATE 
DATABASE 


DATABASE 


CLOSE 
DATABASE 
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creates a database directory, sets up the 
system catalogs, and makes the new data- 
base the current database. There can be 
no more than one current database at 
any time. 


selects a database and makes it the 
current database. There can be no more 
than one current database at any time. 


closes the current database files and 
leaves no database current. The only 
RDSQL statements permitted when there 
is no current database are: 


• CREATE DATABASE 
• DATABASE 
• DROP DATABASE 


DROP 
DATABASE 


CREATE TABLE 


ALTER TABLE 


• START DATABASE 


deletes all tables, indexes. and system 
catalogs. If no other files are present in 
the database subdirectory, the subdirec- 
tory is also deleted. 


creates a table and defines the columns 
and their data types. 


adds and drops columns from a table and 
modifies data types of existing colurims. 


RENAME TABLE changes the name of a table. 


DROP TABLE 


CREATE VIEW 


DROP VIEW 


deletes all data and indexes for a table 
and erases its entry in the system 
catalogs. 


defines a table selected from rows and 
columns of existing tables and views. As 
the underlying tables change, so does the 
view built upon them. See the section 
"Views" later in this chapter for more 
information about views. 


deletes the definition of the view from 
the system catalogs along with any views 
defined in terms of the one that is 
dropped. The underlying tables are 
unaffected. 
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CREATE 
SYNONYM 


DROP 
SYNONYM 


RENAME 
COLUMN 


CREATE INDEX 


ALTER INDEX 


DROP INDEX 


UPDATE 
STATISTICS 
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defines an alternative name for a table or 
a view. A synonym is effective only for 
the user who creates it and can be 
dropped only by its creator. This means 
that if several people want to use the 
same synonym, they must each create the 
synonym. For INFORMIX·4GL programs, 
the creator is the user who runs the 
program that creates the synonym. 


. deletes a synonym from the system 
catalogs. 


changes the name of a column. 


creates an index on one or more columns 
of a table. See the section "Indexing 
Strategy" later in this chapter for more 
information on indexes. 


clusters a table in the order of an 
existing index or releases an index from 
the cluster attribute. 


deletes a previously CREATEd index. 


updates the system catalogs by determin- 
ing and inserting the number of rows in 
the indicated tables. RDSQL uses this 
information in optimizing queries, but 
does not automatically update the system 
catalogs after each INSERT or 
DELETE. 


Data Manipulation 


The data manipulation statements are the most frequently used 
RDSQL statements: 


DELETE 


INSERT 


SELECT 


UPDATE 


deletes one or more rows from a table. 


adds one or more rows to a table. 


retrieves data from one or more tables. 


modifies the data in one or more rows of a 
table. 


SELECT is the most important and the most complex RDSQL 
statement. Although its syntax is defined in detail in Chapter 
7, the following examples illustrate its use. 


SELECT 
Iname, 
company 
INTO p_lname, 
p_company 


FROvl customer 
WHERE customer_num = 101 


This statement queries the customer table and returns the 
single row for which the customer number is 101. From that 
row, it selects and places the values in the columns correspond- 
ing to the contact's last name and company name in the 
program variables p_Iname and p_company. 


SELECT @q uant i t y, 
@t 0 t a IJ 
ric e 
INTO quantity, 
totalJrice 
FROv1 
items 
WHERE order_num = 1001 


This example shows another SELECT statement that returns a 
single row. In this example, the program variables quantity 
and total_price have the same identifier as the corresponding 
columns in the items table. There is no conflict here since the 
prefixed @ distinguishes the column name from the program 
variable. 
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A SELECT statement that returns a single row is called a 
singleton SELECT statement and can stand alone. The section 
"Cursor Management" that follows describes how to handle 
SELECT statements that return more than one row. 


Cursor Management 


The following sections describe how to use a cursor to handle 
SELECT statements that return more than one row, or to 
insert rows into the database as a block. 


SELECT Cursors 


In the examples of a previous subsection, the SELECT state- 
ment returned exactly one row, and the values returned to the 
program variables are unambiguous. When more than one ro\v 
can be returned, it is necessary to have a device to distinguish 
one row from another. This device is called a cursor. 


The set of rows returned by a SELECT statement is called the 
active set for the statement. Within an INFORMIX-4GL program, 
you can work with only one row of the active set at a time. 
This row is called the current row and is referenced by 
a cursor. 


A cursor can be in one of two states: open or closed. When a 
SELECT cursor is in an open state, it is associated with an 
active set and can point to the current row, between two rows, 
before the first row, or after the last row. When it is in a 
closed state, the cursor no longer is associated with an active 
set, although it remains associated with the SELECT 
statement. 


The following sections describe how to use the cursor 
management statements to process rows returned by a 
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SELECT statement. (For complete information on the syntax 
of each statement, see Chapter 7 of the INFORMIX-4GL 
Reference Manual.) 


Associating a Cursor with a SELECT Statement 


You can use the DECLARE statement to name a cursor and 
associate it with a SELECT statement. You can DECLARE a 
non-scrolling cursor that allows rows to be updated or retrieved 
from the active set in consecutive order, or you can DECLARE 
a scrolling cursor that allows rows to be retrieved in random 
order. For example, the following DECLARE statement 
associates a scrolling cursor named ~curs with a SELECT 
statement that retrieves all the rows from the customer table: 


DECLARE 
~curs 
SCROLL CURSOR FOR 
SELECT 
• 
FROM customer 


The following DECLARE statement associates a non-scrolling 
cursor with a SELECT statement that retrieves customer rows 
based on a last name that the user supplies: 


PROMPT "Enter 
a 
last 
name: 
"FOR last 
name 


DECLARE cust curs CURSOR FOR 
SELECT • IFROM customer 
WHERE 
Iname MATCHES last 
name 


A cursor name has meaning only from the point at which it is 
DECLAREd to the end of the source code file. This means 
that the DECLARE statement for a cursor must physically 
appear before any statement that makes reference to it. 
For example, the following program will not compile because 
the DECLARE statement for ~curs appears after the 
FOREACH statement that refers to it. (See the following sec- 
tion "Retrieving and Processing Rows" for more information 
about FOREACH.) 
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DATABASE stores 


MAIN 


DEFINE p_customer 
RECORD LIKE customer.· 


OPEN FORM custform FRQ..t1 "customer" 


DISPLAY FORM custform 


# 
INCORRECT 


FOREACH 
~curs 
INTO p_customer.· 


DISPLAY BY NAME p_customer.· 


END FOREACH 


END MAIN 


FUNCT ION ge t_cu r s () 


DECLARE 
~curs 
CURSOR FOR 
SELECT • 
FROM customer 


END FUNCTION 


Retrieving and Processing Rows 


Once you have declared a cursor for a SELECT statement, you 
can use either the FOREACH statement or OPEN, FETCH, 
and CLOSE to retrieve and process the rows specified by the 
SELECT statement. 
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The FOREACH Statement. 
You can select the rows and 
execute a series of statements for each row returned by a query 
using the FOREACH statement. The following example uses a 
FOREACH statement to retrieve and display rows in the 
customer table: 


PRO'v1PT "Enter 
a 
last 
name: 
"FOR 
last 
name 


DECLARE 
~curs 
CURSOR FOR 
SELECT 
* FRQ,01 customer 
WHERE 
Iname MATCHES 
last_name 


FOREACH 
~curs 
INTO p_customer.* 


DISPLAY BY NAME p_customer.* 


END FOREACH 


When I~FORM:IX-4GLencounters the FOREACH statement in 
this example, it runs the query and repeatedly performs the 
following operations until the active set is exhausted: 


• 
Retrieves the next row from the active set and stores it in 
the p_customer record 


• 
Displays the values in the p_customer record on 
a screen form 


• 
Executes all additional statements within the 
FOREACH loop 


You can use the FOREACH statement when you want to 
retrieve the rows specified by a SELECT statement and pro- 
cess them in consecutive order. (In such cases, the cursor you 
specify in the FOREACH statement need not be a scrolling 
cursor.) 
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When you need to process the rows returned by a SELECT 
statement in random order, you must DECLARE a scrolling 
cursor and use the OPEN, FETCH, and CLOSE statements 
described in the following section. 


OPEN, FETCH, and CLOSE. 
You can use OPEN, FETCH, 
and CLOSE when you need to explicitly control the behavior of 
a cursor: 


OPEN 
puts the cursor in an open state with regard to the 
SELECT statement. The OPEN statement causes 
the SELECT statement to be run with the current 
program variables and leaves the cursor pointing 
just before the first row of the resulting active set. 
'While the cursor is in an open state, subsequent 
changes to any program variables that appear in the 
SELECT statement associated with the cursor do 
not affect the active set. 


FETCH 
advances the cursor to the specified row (either 
FIRST, LAST, NEXT, PRIOR or PREVIOUS, 
ABSOLUTE n, or RELATIVE m) and retrieves the 
values from that row. If a FETCH statement moves 
the cursor before the first row or after the last row, 
the error variable status has the value NOTFOUND 
(= 100) as does the SQLCODE component of the 
SQLCA record (seethe discussion later in this 
chapter). NOTFOUND indicates that either end of 
the active list has been reached. 


Note: When you initially fetch a row with a scrolling 
cursor, all the rows in the active set up to and 
including the fetched row are placed in a temporary 
file and remain there until you close the cursor. 
Ifyou then fetch the same row or any row prior to 
it, INFORMIX-4GL makes the retrieval from the 
temporary file instead of from the database. This 
means that subsequent changes to the database may 
not be reflected in the active set used by a scrolling 
cursor. 
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CLOSE 
puts the cursor in a closed state and releases the 
active set. No statements referring to the cursor, 
other than OPEN, are operative. 


The following example shows how to use these cursor manage- 
ment statements to retrieve and display rows in the customer 
table. 


MAIN 


DECLARE 
~curs 
SCROLL CURSOR FOR 
SELECT 
* FROM customer 


WHERE 
Iname MATCHES 
last_name 


OPEN 
~cu r s 


FETCH FIRST 
~curs 
INTO p_customer.* 


IF status = NOTFOUND THEN 
CALL mess("No customers 
found.") 
ELSE 
DISPLAY 
BY 
NAME p_customer.* 
CALL viewcust() 
END 
IF 


CLOSE 
~cu rs 


END MAIN 


The main program includes the following statements: 


• 
The DECLARE statement associates a scrolling cursor 
called q_curs with the SELECT statement that retrieves 
rows from the customer table. 
(The program uses a scroll 
cursor since the rows specified by the SELECT statement 
are retrieved in random order.) 


• 
The OPEN statement runs the SELECT statement with the 
current value of last_name and leaves the cursor pointing 
just before the first row of the active set. 
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• 
The FETCH FIRST statement attempts to retrieve the first 
row of the active set. 


• 
The IF statement displays a message indicating that the 
active set is empty if the value of the status variable is 
NOTFOUND. Otherwise, it displays the first row on a 
screen form and calls a function that allows the user to 
browse through the rows in the active set. 


• 
The CLOSE statement releases the active set after all rows 
have been processed. 


The viewcust function displays a menu that lets the user 
browse through the rows in the active set: 


FUNGT ION 
'0' i ewe u 5 t ( ) 


MENU "BRONSE:tt 


COvtvlAND "Next". "View 
the 
next 
customer 
in 
the 
I is1" 
FETCH 
NEXT Leurs 
INTO p_customer.- 
IF status = NOTFOUND THEN 
CALL 
mess(ffNo more 
customers 
in 
this 
di rect ion 
tt) 
FETCH 
LAST 
Q..._curs 
INTO ·p_customer.· 
END 
IF 
DISPLAY BY NAME p_customer.· 


COvf.I1AND "Previous" 
"VIew 
the 
previous 
customer 
in 
the 
I iSl" 
FETCH PREVIOUS 
~curs 
INTO p_cuslomer.· 
IF sial us = NOTFOUND THEN 
CAL L 
me 5 s ("No 
rna r e 
ellS I orne r 5 
j nth j 5 
d ire c t ion 
,,) 
FETCH FIRST 
~curs 
INTO p_customer.- 
END 
IF 
DISPLAY 
BY 
NAME p_customer 
• 


CCJvt.AAND nFi rst" "View 
the 
f i rsf 
customer 
in 
the 
list" 
FETCH FIRST Leurs 
INTO p_customer 
• 
DISPLAY 
BY 
NAME p_customer.· 


CO\f.AAND "Last" "View 
the 
las1 
customer 
In 
the 
I isl" 
FETCH 
LAST Leurs 
INTO p_customer 
• 
DISPLAY 
BY 
NAME p_customer.· 


COvtvtAND "Exit" "Leave 
the menu" 
EXIT MENU 


END MENU 


END 
FUNC T ION 


This function consists of a MENU statement that contains the 
following COMMAND clauses: 


Next 
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includes a FETCH NEXT statement that 
attempts to retrieve the next row of the active 
set. The IF statement returns the cursor to the 


Previous 


First 


Last 


Exit 


last row and displays a message if the value of 
the status variable indicates that the cursor has 
moved beyond the last row of the active set. 
The DISPLAY BY NAME statement displays 
the row retrieved by the appropriate FETCH 
statement on the screen. 


includes a FETCH PREVIOUS statement that 
attempts to retrieve the previous row of the 
active set. The IF statement returns the cursor 
to the first row and displays a message if the 
value of the status variable indicates that the 
cursor has moved beyond the first row of the 
active set. The DISPLAY BY NAME 
statement displays the row retrieved by the 
appropriate FETCH statement on the screen. 


includes a FETCH FIRST statement that 
retrieves the first row in the active set and 
displays it on the screen. 


includes a FETCH LAST statement that 
retrieves the last row in the active set and 
displays it on the screen. 


includes an EXIT MENU statement that 
terminates the MENU statement. 
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Note: When you open a cursor that identifies a SELECT 
statement containing a program variable, INFORMIX-4GL runs 
the SELECT statement with the current value of the program 
variable. In the following example, the active set produced by 
the first OPEN statement diff-ers from the active set produced 
by the second OPEN statement because the value of 
last_name changes from Baxter to Grant: 


LET 
last_name 
= "Baxter" 


DECLARE 
~curs 
SCROLL CURSOR FOR 
SELECT 
• 
FROM customer 


WHERE 
Iname MATCHES 
last_name 


OPEN 
~cu r s 


CLOSE 
~curs 


"Grant" 


OPEN 
~cu r s 


Deleting or Updating the Current Row 


You can use special forms of DECLARE, DELETE, and 
UPDATE to delete or update the current row in an active set. 
This requires that you use a non-scrolling cursor to process the 
rows returned by a SELECT statement, and that the SELECT 
statement not inch,lde an ORDER BY clause. 
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Deleting the Current Row. 
To delete a row in an active set, you 
must include a FOR UPDATE clause in the DECLARE state- 
ment for a non-scrolling cursor and a WHERE CURRENT OF 
clause in a subsequent DELETE statement, as follows: 


PRWPT "Enter 
a 
last 
name: 
"FOR 
last_name 


DECLARE 
~cu r s CURSOR FOR 
SELECT· 
FROM 
customer WHERE 
Iname MATCHES 
last_name 
FOR UPDATE 


FOREACH 
q_curs 
INTO p_customer 
• 


DISPLAY 
BY NAME p_cuslomer.· 


PRo.APT 
nDo 
you 
want 
10 delete 
this 
customer 
(yIn) 
? 
tt 
FOR 
answer 


IF answer = 
,ty" 
THEN 
DELETE 
FROM customer WHERE CURRENT OF 
~curs 


CLEAR 
FORM 
END 
IF 


END ,FOREACH 


The cursor remains between rows after a DELETE \VHERE 
CURRENT OF statement is executed. This means you cannot 
refer to it in another DELETE or UPDATE statement until 
you use a FETCH statement to advance the cursor to the next 
row. (In this example, the FOREACH statement automatically 
performs the FETCH.) 
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Updating the Current Row. 
You can update the current row if 
you include a FOR UPDATE clause in the DECLARE state- 
ment for a non-scrolling cursor and a \VHERE CURRENT OF 
clause in a subsequent UPDATE statement. The following 
example allows the user to update the address information in 
the current row: 


DECLARE 
~curs 
CURSOR FOR 
SELECT· 
FROM customer 
FOR UPDATE 


FOREACH 
~curs 
INTO p_customer.· 


DISPLAY 
BY 
NAME p_cuslomer.· 


PRa.APT 
"Do 
you 
want 
to 
change 
the 
customer's 
address 
(y 
n) 
? 
tI 
FOR answer 


IF 
answer = "'Itt 
THEN 


INPUT 
BY 
NAME p_customer.addressl. 
p_customer 
address2. 
p_c u s t orne rei I 'I . 
P customer 
stale. 
p_customer. Z ipcode 
WITHOUT DEFAULTS 


UPDATE 
customer 
SET address1 = p customer.address'. 
address2 = p=customer.address2, 
c j t Y = p_cus t orne rei t'l. 
state = p_customer.state. 
zipcode = p customer.zipcode. 
WHERE CURRENT OF ~curs 


END 
IF 


END 
FOREACH 


If you specify one or more columns in the FOR UPDATE 
clause of the DECLARE statement, you can update only those 
columns in a subsequent UPDATE WHERE CURRENT OF 
statement. If you do not list columns in a FOR UPDATE OF 
column-list clause, you can update any column retrieved in the 
select. INFORMIX-4GL can usually execute the updates more 
quickly if you include a FOR UPDATE clause in the 
DECLARE statement. 
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The following example allows the user to update the fname 
and Iname columns of the current row: 


DECLARE 
~curs 
CURSOR 
FOR 
SELECT * FROM customer 
FOR UPDATE OF 
f name. 
I name 


FOREACH 
~curs 
INTO p_customer.* 


DISPLAY 
BY 
NAME p_customer.* 


PROMPT "Do you wan t 
to change" 
"the contact's name 
(yIn) 
~ 
" 
FOR answer 


IF answer = "y" THEN 


INPUT 
BY 
NAME p_customer.fname, 
p_customer.lname 
WITHOUT DEFAULTS 


UPDATE customer 
SET 
fname = p_customer. fname, 
I name 
= 
p_c us tome r . Iname 
WHERE CURRENT OF 
~curs 


END 
IF 


END FOR EACH 


The position of the cursor does not change after an UPDATE 
WHERE CURRENT OF statement is executed. 
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INSERT Cursors 


You can associate a cursor with an INSERT statement as well 
as a SELECT statement. The INSERT cursor permits more 
efficient insertion of data into a database by buffering the data 
in memory and writing to the disk only when the buffer is full. 
The following statements allow you to declare and manipulate 
an INSERT cursor. (For complete information about the syn- 
tax of each statement, see Chapter 7 of the INFORMIX-4GL 
Reference Manual). 


DECLARE associates a cursor with an INSERT statement. 
(The INSERT statement may not contain an 
embedded SELECT statement.) 


OPEN 


PUT 


FLUSH 


CLOSE 


sets up an insert buffer for an INSERT cursor. 


stores a row in the INSERT buffer for later 
insertion into the database. When you fill the 
buffer (by executing a series of PUT statements), 
RDSQL automatically inserts the rows into the 
appropriate table as a block. 


forces RDSQL to insert the buffered rows into the 
database without closing the INSERT cursor. 
You can force the insertion using the FLUSH 
statement, but you cannot delay insertion by not 
using the FLUSH statement. 


flushes the insert buffer and closes the INSERT 
cursor. 
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For example, you can use these cursor management statements 
to insert customers into the customer table block by block. as 
follows: 


DECLARE 
ins_curs CURSOR FOR 
INSERT 
INTO customer 
VALUES (p_customer.·) 


LET answer ="y" 


w-lILE answer = "y" 


INPUT 
BY 
NAME p_customer. fname 
THRU p_customer .phone 


LET p_customer.customer_num = a 


PROv1PT "Do you want 
to enter" 
"another 
customer 
(yin)? 
" 
FOR answer 


ENDw-l1 LE 


CLOSE 
ins_curs 


This example includes the following statements: 


• 
The DECLARE statement associates a cursor called 
ins 
curs with an INSERT statement that inserts a row 
into the customer table. 


• 
The OPEN statement sets up the insert buffer for the 
INSERT cursor. 


• 
The WHILE loop includes statements that insert informa- 
tion entered on a screen form into the customer table block 
by block. Specifically, the INPUT statement allows the user 
to enter customer information on a screen form and stores 
it in the p_customer record. The PUT statement stores 
the current values in the p_customer record in the insert 
buffer. If the insert buffer becomes full as the result of a 
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PUT statement, RDSQL automatically inserts the rows into 
the customer table as a block. 


• 
The CLOSE statement inserts any rows that remain in the 
insert buffer into the customer table and closes the 
INSERT cursor. 


When you use an insert cursor, you should CLOSE the cursor 
to insert any buffered rows into the database before allowing 
your program to end. The user may lose data if the cursor is 
not closed properly. For example, if the user presses the 
INTERRUPT key during input in the following program, 
IXFORMIX-4GL closes the INSERT cursor before leaving the 
program. (This ensures that any remaining rows in the insert 
buffer are inserted into the database before the program 
stops.) 


DEFER 
INTERRUPT 


DECLARE 
,ns_curs CURSOR FOR 
INSERT 
INTO 
customer 
VALUES 
(p_customer.") 


LET answer = 'Iy'l 


~ILE 
anSWEr = ny" 


INPUT 
BY 
NA~ 
P customer. fname 
THRU 
p_customer .phone 
ON KEY 
(INTERRUPT) 


CL OSE 
Ins _cur s 
EXIT 
PROGRAM 
END 
INPUT 


LET 
~_customer.customer_num= 0 


PRo.APT 
tlDo 
yOu 
want 
to enter 
another 
customer 
(yin) 
7 
" 
FOR 
E\nswer 


END V>HILE 


CL OSE 
ins _c u ( S 


2-28 Cursor Management 


·You can determine whether INFORMIX·4GL successfully executed 
a PUT, FLUSH, or CLOSE statement by examining the values 
of the status and SQLCA.SQLERRD[3] variables. (See the 
section "SQLCA Record" later in this chapter for more infor- 
mation on these variables.) 
IfRDsQL simply puts a row in the 
insert buffer, it assigns the following values to these global 
variables: 


status = 
0 
SQLCA.SQLERRD[3] = 
0 


If RDSQL successfully inserts a block of rows into the database 
as the result of a PUT, FLUSH, or CLOSE statement, it 
assigns the following values: 


status = 
0 
SQLCA.SQLERRD[3] = 
the number of rows inserted 


If, as the result of a PUT, FLUSH, or CLOSE statement, 
RDSQL is unsuccessful in its attempt to insert an entire block of 
rows into the database, it assigns the following values: 


status = 
a negative number 
corresponding to the error message 
SQLCA.SQLERRD[3] = 
the number of rows successfully inserted 


Note: 
If your database has transactions, you must include 
all PUT statements within a BEGIN WORK-COMMIT 
WORK or BEGIN WORK-ROLLBACK WORK block. 
Both COM:l\HT WORK and ROLLBACK WORK close all 
open cursors. You should also close an INSERT cursor before 
committing work so you can check that the insertion was 
successful. 


Dynamic Management 


The preceding discussion assumes that you know what the 
RDSQL statements are when you write your IXFORMIX-4GL pro- 
grams. That is the case for most applications where you are 
performing predetermined activities on your database. There 
are several advanced applications, however, where you wiII not 
know the statement at compile time. These include the 
following programs: 


• 
Interactive programs where the user supplies input at 
runtime from the keyboard 


• 
Programs intended to work with different databases whose 
structure can vary 


In situations like these, you must work with dynamically 
defined statements. A brief description of the dynamic 
management statements follows: 


PREPARE 
takes a character string, interprets it as an 
RDSQL statement, and assigns it to a statement 
identifier. Subsequent dynamic management 
statements refer to the RDSQL statement through 
the statement identifier. 


EXECUTE 
runs the previously PREPAREd statement 
associated with the statement identifier. Use 
EXECUTE for all prepared statements except 
the following statements: 


• 
SELECT statements 
• 
INSERT statements that use an insert cursor 


DECLARE 
has a version that declares a cursor for a 
PREPAREd SELECT or INSERT statement. 
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Preparing Statements 


You can use the PREPARE statement with either a character 
string or a character variable that evaluates to an RDSQL state- 
ment. The form of the PREPARE statement you choose 
depends on the type of input (if any) the statement requires. 
You can use either form of the PREPARE statement if the 
statement requires no input or input for values. If the state- 
ment requires input for RDSQL identifiers such as column 
names, you must use the PREPARE statement with a 
character variable. 


In general, you can improve the performance of your programs 
by preparing statements you plan to execute many times. 
Specifically. you might want to prepare a statement that 
requires different input each time it is executed. 


Note: You can prepare any RDSQL statements except the 
follO\ving statements: 


CLOSE 
DECLARE 
EXECUTE 
FETCH 


OPEN 
PREPARE 
SELECT with an INTO clause 


See the section "RDSQL Statement Summary" earlier in this 
chapter for more information about RDSQL statements. 
Chapter 1 describes the INFORMIX-4GL statements you cannot 
prepare. 
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Statements That Require No Input 


If a statement requires no input, you can prepare it from either 
a character string or character variable. For example, the 
following statement 


PREPARE sl 
FROv1 "SELECT 
• 
FROv1 customer" 


produces the same result as 


DEFINE sel_stmt 
CHAR(25) 


LET sel 
stmt = "SELECT 
• 
FROv1 customer" 


PREPARE sl 
FROv1 sel_stmt 


Statements That Require Input for Values 


Similarly, you can use either form of PREPARE when a 
prepared statement requires input for one or more values. 


Preparing a Character String. 
If you use PREPARE with a 
character string, you must use a question mark (?) instead of a 
program variable in the character string as a placeholder for a 
value. Specifically, the question mark can represent a value or 
expression in a character string but not an RDSQL identifier 
(such as a column name or table name). Usually, you use a 
question mark to represent a value in the following clauses: 


• 
The WHERE clause of a SELECT. UPDATE, or DELETE 
statement: 


PREPARE sell 
FROv1 


"SELECT 
• 
FROv1 customer w-iERE 
Iname MATCHES ?" 
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• 
The VALUES clause of an INSERT statement: 


PREPARE 
ins1 
FROM 
"INSERT 
INTO manufact 
VALUES (?, 
?)" 


• 
The SET clause of an UPDATE statement: 


PREPARE 
updl 
FROM 
"UPDATE 
customer 
SET 
zipcode 
= 
? 
\'MERE 
CURRENT 
OF Lcurs" 


When you prepare a statement from a character string, you do 
not need to supply values for the question marks until you 
execute the PREPAREd statement (see the section "Executing 
Prepared Statements" later in this chapter for more 
information). 


Preparing a Character Variable. 
Alternatively, you can prepare 
a statement that requires input for values from a character 
variable. First, you use a LET statement to concatenate the 
variable(s) containing the input to one or more strings that 
represent the rest of the statement. Second, you PREPARE 
the character variable that contains the resulting RDSQL 
statement. 


The following example shows how to use this approach to 
prepare a statement that selects rows from the customer table 
based on a customer number that the user supplies: 


DEFINE 
CUSI 
num 
INTEGER, 
se I~stml CHAR( 100) 


PROv1P TilE n t era 
c u s t orne r 
numb e r: 
" 
FOR 
cust_num 


LET 
sel 
stmt = 


nSEL"E-CT 
• 
FROv1 customer 
~ERE customer_num = 
", 
cust_num 
USING 
"~;:#",I 


PREPARE sell 
FROM sel_slmt 


When I!IlFORMIX-4GL encounters the LET statement in this 
example, it concatenates a character string containing part of 
the SELECT statement to the variable cust_num, which con- 
tains a customer number that the user supplies. 
I1\"FOR~IIX-4GL 


then assigns the resulting string to the large character variable 
sel_stmt and PREPAREs it. 
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When you use this approach, you must supply input values 
when you assign the RDSQL statement to the character variable 
that you will later PREPARE. 


Note: If you use the LET statement to concatenate strings to 
variables that contain CHAR or DATE values, make sure that 
quotes appear around those values in the resulting character 
string. To embed a quote in a character string, you must enter 
a backslash (\) followed by a double quote (tt). For example, 
the LET statement 


lET 
sel 
8tmt 
= "SELECT· 
FRCJ.A customer 
w-iERE 
Iname MATCHES 
'.nu, 


I as t=n arne 
CL I PPED, 
n\fm 


PREPARE 
S1 
FROM sel_slml 


produces the following character string if the current value of 
last 
name is Baxter: 


SELECT" 
FRCU customer 
w-iERE 
I name 
MATCHES 
ttBaxt~r" 


In contrast, the statements like the following do not require 
quotation marks around placeholders for values. 


DECLARE 
~_cu rs 
CURSOR FOR 
SELECT' 
FROM customer WHERE 
Iname MATCHES 
last_name 


PREPARE 
s 1 FROM 
"SELECT· 
FRCM customer 
'M-lERE 
Iname MATCHES 1" 


Statements That Require Input 
for RDSQL Identifiers 


You must use PREPARE with a character variable to prepare a 
statement that requires data for an RDSQL identifier such as a 
column name, table name, user name, view name, or synonym. 
The approach you use is identical to that described in the pre- 
vioussection. First, you concatenate the variable(s) represent- 
ing the RDSQL identifier(s) to one or more character strings that 
contain the rest of the statement. Second, you assign the 
resulting string to a large character variable and PREPARE it. 
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The following example shows how to use this approach to 
prepare a statement that grants the CONNECT privilege to a 
specified user: 


DEFINE P user 
CHAR(12), 
grant_stmt 
CHAR(50) 


PROMPT "Enter 
the 
name of 
user ", 
"to receive CONNECT permission: 
" 
FOR p_user 


LET gran t_s tmt 
= 
"GRANT CONNECT TO " 
p_user 
CLIPPED 


PREPARE sl 
FROM grant 
stmt 


"Vhen I~FORMIX-4GL encounters the LET statement in this 
example, it concatenates a character string containing part of 
the GRANT statement to the character variable p_user, 
which contains a login name. INFORMIX-4GL then assigns the 
resulting string to grant_stmt and PREPAREs it. 


Executing Prepared Statements 


The method for executing a prepared statement depends upon 
the kind of statement you want to run. The EXECUTE state- 
ment runs any prepared statements except those that follow: 


• 
SELECT statements 
• 
INSERT statements that you want to process as a group 


The DECLARE statement has a special form designed to work 
with prepared SELECT and INSERT statements. 
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The EXECUTE Statement 


If you have prepared a non-SELECT statement from a 
character variable or from a character string that does not con- 
tain question marks, you can run it with a simple EXECUTE 
statement. Examples follow: 


PREPARE ., 


FRCf.A "DELETE 
FRCJ..1 
customer 
'M-iERE 
customer_num = 
115" 


EXECUTE ., 


LET 
del __ stml 
= 
"DELETE 
FR~ cuslomer 
'M-IERE 
customef_num = 
115" 


PREPARE 
51 
FRCM del 
5tml 


EXECUTE 
51 


If you prepared a non-SELECT statement from a character 
string that does contain question marks, you must use the 
EXECUTE statement with a USING clause. This clause con- 
sists of the USING keyword followed by one or more program 
variables representing the values that replace the question 
marks in the prepared character string. 


2-36 Dynamic Management 


The EXECUTE statement in the following example executes a 
DELETE statement using a customer number that the user 
supplies. 


PREPARE 51 


FRQ.A uDELETE 
FRq.A customer 
'M-iERE 
customer_num = 
?" 


PRW?T 
"00 
you 
want 
10 delete 
8 
customer 
(yIn) 
: 
FOR 
answer 


~ILE answer = ny" 


PRQ.1F T 
"E n t era 
c u 5 tome r 
n umt e r 
FOR 
c u 5 I 
n urn 


EXECUTE 
51 
USING cust_num 


IF status = 0 THEN 
DISPLAY "Row deleted n 
ELSE 
CALL mess(nUnable 
to delete 
the customer 
row") 
END 
IF 


PRQ.APT 
"Do 
you 
want 
to 
delete 
another 
customer 
(yIn): 
FOR 
answe r 


END I'M ILE 


When INFORMIX-4GL executes the prepared DELETE statement 
in this example, it substitutes the current value of cust_num 
for the question mark in the character string. 
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Running Prepared SELECT Statements 


If you prepared a SELECT statement from a character variable 
or from a character string that does not contain question 
marks, you can use a DECLARE statement with either 
FOREACH or OPEN, FETCH, and CLOSE. Two examples 
follow: 


LET se I stmt 
"SELECT • 
FROvl customer 'M-iERE 
Iname MATCHES \"". 
last 
name CLIPPED. 
"\"" 


PREPARE sel 1 FROvl sel_stmt 


DECLARE 
~curs 
CURSOR FOR sel 1 


FOREACH 
~curs 
INTO p_customer.· 


DISPLAY BY NAME p_customer.· 


END FOREACH 


PREPARE sel 1 FROvl 


"SELECT 
• 
FROvl customer" 


DECLARE 
~curs 
CURSOR FOR sel 1 


FOR EACH 
~curs 
INTO p_customer.· 


DISPLAY BY NAME p_customer.· 


END FOREACH 
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If you prepared a SELECT statement from a character string 
that does contain one or more question marks, you must use 
the DECLARE statement with an OPEN statement that 
includes a USING clause. As described previously, this clause 
consists of the USING keyword followed by one or more pro- 
gram variables representing the values that replace the question 
marks in the character string. An example follows: 


PREPARE sel 1 FROM 
"SELECT 
• 
FROM customer \M-IERE zipcode MATCHES 
?" 


DECLARE 
~curs 
CURSOR FOR sel 1 


PROMPT "Enter 
a zipcode: 
" FOR zip 


OPEN 
~curs 
USING zip 


\M-IILE TRUE 


FETCH 
~curs 
INTO p_customer.· 


IF status = NOTFOUND THEN 
EX I T \M-II LE 
END 
IF 


DISPLAY 
BY 
NAME p_customer.· 


END \M-II LE 


CLOSE 
~cu r s 


When INFORMIX-4GL opens the cursor for the prepared' 
SELECT statement in this example, it substitutes the current 
value of zip for the question mark in the character string. 
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A Note on Preparing 
and Executing SELECT Statements for Update: 


A previous section entitled "Deleting or Updating the Current 
Row" describes how to use the DECLARE FOR UPDATE 
statement and a subsequent DELETE or UPDATE statement 
to delete or update the current row. If you want to use 
DECLARE FOR UPDATE with a prepared SELECT state- 
ment, make sure the FOR UPDATE clause appears as part of 
the prepared character string or character variable and not as 
part of the DECLARE statement. An example follows: 


PREPARE 81 
FROvl "SELECT * FROvl customer 
FOR UPDATE" 


DECLARE 
~curs 
CURSOR FOR s1 


FOREACH 
~curs 
INTO p_customer.* 


DELETE 
FROvl customer WHERE CURRENT OF 
~curs 


END FOREACH 


Running Prepared INSERT Statements 


If you have PREPAREd an INSERT statement, you can run it 
by using the EXECUTE statement or the PUT statement. A 
previous section, "The ExEcUTE Statement," describes how 
to use the EXECUTE statement if you want RDSQL to insert 
one row into the database at a time. This section explains how 
to DECLARE a cursor and use the PUT statement to insert 
rows into the database through an insert buffer. 


If you prepared an INSERT statement from a character vari- 
able or from a character string that does not contain question 
marks, you can use the DECLARE, OPEN, FLUSH and/or 
CLOSE statements with a simple PUT statement, as follows: 


2-40 Dynamic Management 


PREPARE s1 
FROvl 


"INSERT 
INTO manufaet 
VALUES 
('WLS", 
'Wi II is") 


DECLARE 
leurs CURSOR FOR 
51 


OPEN leurs 


PUT 
leurs 


CLOSE ieurs 


If you prepared an INSERT statement from a character string 
that does contain one or more question marks, you must use 
the DECLARE, OPEN, FLUSH, and/or CLOSE statements 
with a PUT statement that includes a FROM clause. This 
clause consists of the FROM keyword followed by one or more 
program variables representing the values that replace the 
question marks in the character string. An example follows: 


PREPARE 
s 1 
FRCJ,1 


"INSERT 
INTO customer 
(customer_num, 
compeny) 
VALUES (0, 
7)" 


DECLARE 
ins_curs 
CURSOR 
FOR ., 


LET answer = "y" 


Wi I LEa n swe r 
= 
"ytt 


Prompt "Enter a customer: 
" 
FOR p customer 
compeny 


PUT 
ins_curs 
FRCtA 
p 
customer.compeny 


PRaAPT 
"Do 
you 
want 
to enter 
another 
customer 
(yin) 
? 
tf 
FOR answer 


END 
1'>\-11 LE 


CLOSE 
i ns_cu r 5 


When INFORMIX·4GL executes the PUT statement in this exam- 
ple, it substitutes the current value of p_customer.company 
for the question mark in the prepared INSERT statement and 
stores the row in the insert buffer for later insertion into the 
database. 
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Data Access 


A user has access to the database, a table, and to specific 
columns within a table only when the Database Administrator 
(DBA) or the owner of the table specifically grants these 
privileges. You can temporarily limit access to a table by exe- 
cuting the LOCK TABLE statement. (Under transactions, 
RnSQL locks the affected rows until the transaction is complete. 
Explicit table/record locking is generally not required.) 
The 
follo\-:ing RnSQL statements affect data access 


GRANT 


REVOKE 


LOCK TABLE 


grants database access privileges to 
specific users or to the public. 


removes database access privileges from 
specific users or from the public. 


limits access to the table to the current 
user only or allows other users only to 
read the table. Use the LOCK TABLE 
statement only when making major 
changes to a table in a multi-user 
environment and when simultaneous 
interaction with the table by another 
user would interfere. LOCK TABLE 
decreases the accessibility of the data- 
base, since it prevents other users fron. 
accessing the table. If the database has 
transactions, you must issue a BEGIN 
WORK statement before you can issue 
the LOCK TABLE statement. 


UNLOCK TABLE 
restores access to a previously LOCKed 
table. 


See the later section "User Status and Privileges" for further 
information. 
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Data Integrity 


RDSQL provides data integrity in several ways. You can prevent 
users of the database from changing the same row at the same 
time. The UPDATE statement automatically does this. In 
addition, you can explicitly locking a table, or access the row 
from within a transaction. You can also guarantee data 
integrity by using the recovery feature, which is implemented 
with transactions, or by using audit trails. This section 
describes transactions and audit trails; RDSQL locking state- 
ments are considered in the section "Locking" later in this 
chapter. 


Transactions 


RDSQL provides data integrity on the database level by imple- 
menting transactions. A transaction is a series of operations 
on a database (RDSQL statements) that you want to be com- 
pleted entirely or not at all. Examples of transactions are 
abundant in bookkeeping where several operations on several 
different accounts must be made as a unit or the books will be 
out of balance. Your INFORMIX·4GL programs can ensure the 
data integrity of your database by using the following 
statements: 


BEGIN WORK 
marks the beginning of a transaction. 


COMMIT WORK 
marks the end of a transaction by 
authorizing all changes to the data- 
base since the last BEGIN WORK 
statement. COMMIT WORK releases 
all row and table locks. 


ROLLBACK WORK 
marks the end of a transaction by 
revoking all changes to the database 
since the last BEGIN WORK 
statement. 


START DATABASE 
initiates a new transaction log file. 
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ROLLFORWARD 
DATABASE 
uses a transaction log file to restore a 
database from backup. 


To use transactions, your database must have a transaction log. 
You can create the transaction log by including the WITH 
LOG IN clause in the CREATE DATABASE statement. This 
statement creates not only the database but also a transaction 
log file that keeps track of all modifications to the database. 
Alternately, you can execute the START DATABASE 
statement and initialize a new database transaction log. 


When you want to perform a series of operations that you 
consider a unit, you issue the BEGIN WORK statement. This 
statement causes all subsequently altered rows of the database 
tables to be locked against modification by others (although 
others can view them). When you are satisfied that the series 
of operations has produced the desired results, you terminate 
the transaction with a COMMIT WORK statement. If you are 
not satisfied with the results, you can terminate the transaction 
with a ROLLBACK WORK statement. The ROLLBACK 
WORK statement restores the database to the state that 
existed when you issued the BEGIN WORK statement-with 
an important exception. All data definition statements are 
treated as singleton transactions; that is, if they were executed 
successfully, they are committed and are not rolled back. 
(RDSQL data definition statements are those that alter the 
number or names of tables or views, the number or names of 
columns, the data types, or the indexes. See the section "Data 
Definition" earlier in this chapter for more information about 
these statements.) It is recommended that all data definition 
statements not appear within a transaction. 


Both the COMMIT WORK and the ROLLBACK WORK 
statements unlock the rows and make them accessible for 
modification by others. 


The number of rows that can be locked at one time by all users 
is limited. The actual limit depends on your operating system. 
Try to restrict the definition of a transaction to a few state- 
ments that involve only a few rows. If you expect that the 
number of rows entering into the transaction will be large, 
LOCK the tables involved until the transaction is completed. 
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If the database has transactions, you must issue a BEGIN 
WORK statement before you can issue the LOCK TABLE 
statement. 


Note: The BEGIN WORK, COMMIT WORK, and ROLL- 
BACK WORK statements only work when you CREATEd the 
database with the WITH LOG IN option or STARTed the 
database with a transaction log file. A database created 
without a transaction log is described as a database "without 
transactions." 
A database created with a transaction log is 
described as a database "with transactions." 


If you open or create a database with transactions, but do not 
execute the BEGIN WORK statement, RDSQL treats each state- 
ment as a singleton transaction. Each statement, if it executes 
successfully, is committed, and the database is permanently 
altered. If the statement fails, there is an automatic rollback 
to the status before the statement. 


You must execute cursor manipulation statements inside a 
transaction if your database was created or started with trans- 
actions. You should execute the BEGIN WORK statement 
before opening a cursor. The COMMIT WORK and ROLL- 
BACK WORK statements close all open cursors, although it is 
not recommended that you use them for this purpose. 


You cannot ROLLBACK any of the data definition statements 
nor GRANT or REVOKE statements. For this reason you 
should execute them as singleton transactions. 


If you create a database without transactions, there is no 
automatic recovery from a situation where you want to treat 
several database operations as a single unit of work. For exam- 
ple, under transactions, you can UPDATE several rows as a 
single unit of work. If the UPDATE fails after changing some 
rows but not all, you can ROLLBACK the transaction to the 
original state where no rows are modified. Without trans- 
actions, you must take explicit action to restore the updated 
rows. 


Transaction Log File Maintenance 


The transaction log file can become quite large and, 
periodically, the Database Administrator (DBA) will want to 
archive it on tape and initiate another log file. At the same 
time, the DBA should also create a backup of your database. 
Generally speaking, every log file must have a corresponding 
archive copy of the database. After backing up the log file and 
the database, the DBA must specify an empty log file. To 
reuse the same log file, the DBA can create an empty log file 
with the same name as the old one. In UNIX, you can do this 
with the following command: 


cat 
/dev/null > logfile 


To change the name of the log file, the DBA must execute the 
START DATABASE statement just before making a backup of 
the database. The START DATABASE statement locks the 
database in EXCLUSIVE MODE while it is operating so that 
no further changes can be made. If START DATABASE fails, 
no database is open. 


If the database is without transactions and you want to use 
transactions, the DBA must execute the START DATABASE 
command just before making a copy of the database. 


If there is a backup copy of the database and a transaction log 
file that begins with the operations executed immediately after 
the backup was made, the DBA can bring the backup database 
up to date with the ROLLFORWARD DATABASE statement. 
This statement recovers the database through the last ter- 
minated transaction. The DBA must load the backup database 
files and execute the ROLLFORWARD DATABASE state- 
ment. After rolling the database forward, the DBA is the only 
one who has access to the database, since it is left in an 
exclusive mode. This state allows the DBA to check the data- 
base for errors before making it generally available. Logging 
does not occur during this checking phase. The DBA must 
close the database when it has been restored correctly. 
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Audit Trails 


An audit trail is a file that c.ontains a history of all additions, 
deletions, updates, and manipulations to a database table. An 
audit trail serves a purpose similar to that of a transaction log: 
each is used to maintain a record of modifications to a 
database, and each can be used to update backup copies of a 
database. 


Three audit trail statements are available to protect the 
integrity of a table: 


CREATE AUDIT 
creates an audit trail for a table. 
DROP AUDIT 
removes the audit trail on a table. 
RECOVER TABLE restores a table using the audit trail. 


Creating an Audit Trail 


Use the CREATE AUDIT statement to create an audit trail file 
and to begin writing the audit ttail. The format is 


CREATE AUDIT FOR table-name IN "pathname" 


where table-name is the name of the table for which you want 
to create an audit trail file and pathname is the full pathname 
of the audit trail file. The audit trail file should be on a physi- 
cal device other than the one that holds the data so that a sys- 
tem failure affecting the device that holds the data does not 
also damage the audit trail. If your computer system has more 
than one hard disk, the audit trails should be<cwritten to a disk 
not containing the data. 


To use the audit trail, make a backup copy of the table after 
you have executed a CREATE AUDIT statement but before 
you have made any changes to the table. Once you have 
started the audit trail and have made a backup, you are ready 
to work with the table. 


You can drop and create an audit trail file whenever you want. 
Drop and create the audit trail files just before you make a 
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complete backup of the device containing the data file. If a 
system failure should occur, you can use the audit trail to 
backup the table from the time of the last backup to the time 
the failure occurred. 


Recovering a Table 


In the event of a system failure, you can use the RECOVER 
TABLE statement to restore a database table by using a 
backup copy of the table and an audit trail file. You must first 
restore a backup copy of the table. The backup copy must be 
in the original state that it was in when the audit trail was 
started. If it is not in the original state, the recovery fails. 
The format of the recovery statement is 


RECOVER TABLE table-name 


where table-name is the name of the table you want to recover. 


Once you recover the table, use the DROP AUDIT statement 
to remove the contents of the audit trail file. Then run the 
CREATE AUDIT statement to start a new audit trail file. 
Finally, make a new backup copy of the table. 


Comparison of Transactions and Audit Trails 


Transactions provide data integrity in two ways. First, they 
guarantee that RDSQL statements are either successfully com- 
pleted or are completely canceled. If, for example, you update 
several rows of one or more tables within a transaction, the 
entire update is guaranteed either to succeed by updating all 
rows, or to fail without changing any rows. Second, the trans- 
action log can be used to recover an entire database. 


Audit trails are associated with individual tables. They do not 
guarantee that modifications to several rows of a table either 
succeed entirely or fail without any effect. An audit trail file 
can be used only to recover the table for which it is created. 
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You should consider using audit trails in place of a transaction 
log only when you have one or a few critical tables and you de> 
not need the additional facilities provided by transactions. 
If you need to maintain the integrity of the database as a 
whole, or need the guarantee that RDSQL statements are 
executed as a unit either entirely or not at all, you must use 
transactions. 


User Status and Privileges 


When you create a database, you are automatically the Data- 
base Administrator (DBA) of that database and are the only 
one who has access to the database. Another user does not 
have access to a database until you grant the CONNECT 
privilege to that person. Another user cannot create or drop 
tables and indexes unless granted the RESOURCE privilege. 
Only the Database Administrator (you, initially) can grant 
these privileges. You can also grant the DBA privilege to 
another user. The DBA privilege extends all the powers of the 
Database Administrator to the grantee, including the ability to 
alter the system tables; to drop, start, and roll forward the 
database; and to grant CONNECT, RESOURCE, and DBA 
privileges to others. 


If you have the RESOURCE privilege, you have the CON- 
NECT privilege by default. With the DBA privilege, you have 
both the RESOURCE and CONNECT privileges. You can 
only revoke the privilege of a DBA grantee; you cannot revoke 
your own DBA privilege. If you, as the creator of a database, 
grant DBA privileges to another user, that user can revoke the 
DBA privilege from you, the database creator. This last prop- 
erty permits the transfer of authority from the maker of the 
database application to the person who has responsibility for 
maintaining the database. 


RDSQL allows the CONNECT and RESOURCE privileges to be 
granted to the PUBLIC in addition to specifically named users. 


In addition to these database-level privileges, there are a 
collection of table-level privileges that can be granted by the 
owner of a table. These permit the grantee access to specific 
columns for the purpose of executing SELECT or UPDATE 
statements, or give the grantee authority to insert new rows, 
delete old rows, create indexes, and alter the structure of the 
table. 


Several of the RDSQL statements (ALTER TABLE, ALTER 
INDEX, DROP INDEX, DROP TABLE, DROP VIEW, 
GRANT, RENAME COLUMN, RENAME TABLE, 
REVOKE) can be executed only by the DBA or by the owner 
of the table or index specified in the statement. (You can give 
others the privilege of executing the ALTER TABLE, GRANT, 
and REVOKE statements with certain restrictions.) 
The 
owner of a table is the person (login name) who executed the 
CREATE TABLE statement. The owner of an index is the 
one who executed the CREATE INDEX statement. Execution 
occurs when the compiled INFORMIX-4GL program containing 
the CREATE statements is run, not when the I:'\'FORMIX-4GL 
program is compiled. 
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Indexing Strategy 


There are two major purposes for creating an index on columns 
of a database table: to speed sorting of rows and to optimize 
the performance of queries. When your application writes 
reports involving complex queries through a large database, 
significant time savings can result from judicious indexing. 
The drawback to having an index is that indexes slow down the 
process of inserting new data into the database. When you 
update a table, its indexes may also be modified. This is not a 
problem when you are adding information interactively, a row 
at a time, but can become serious when it is necessary to insert 
a large number of rows from one table into another. 


The solution to this potential conflict between needs is to take 
a dynamic approach to indexing. One of the advantages of a 
relational database built upon C-ISAM is that you do not have to 
decide issues like which columns to index at the time that you 
create your tables. You should write your applications to create 
indexes when you need them and to drop them when they get 
in the way. It takes time to create an index on a table already 
containing data, and you should create only those indexes that 
optimize the queries you make. For example, by judicious 
scheduling, you can create your indexes in anticipation of 
batch report writing during the night and drop them the next 
morning before there are huge data-entry needs. 


The following are hints for strategic indexing. Although the 
last two refer to a single query, they apply when you anticipate 
making a number of queries with the same qualities. 


• 
Do not create indexes for small tables with fewer than 200 
rows. The speed you gain from using an index does not 
overcome the time required to open and search the index 
file on small tables. 


• 
Do not create indexes on a column that has only a few pos- 
sible values. Such columns are those that contain data like 
sex, marital status, yes/no responses, or zip codes in a small 
city. Because data like this produces skewed indexes, 
indexing can cause the optimizing strategy of RDSQL to fail 
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and queries to take longer than if the columns were not 
indexed. If you have a frequent need to have data sorted on 
columns with a small range of possible values, create a tem- 
porary table of the sorted data. Another approach is to 
redesign the database with separate tables for each 
alternative value. 


• 
If the WHERE clause of a SELECT statement imposes a 
condition on a single column, put an index on that column. 
If there are conditions placed on several columns, make a 
composite index on all the affected columns. For the 
SELECT statement 


SELECT 
* 
FROM 
items WHERE order_num > 1015 


put an index on order_num. For the statement 


SELECT * FROM items 
WHERE order_num = 1015 
AND totalJrice > 1000.00 


create a composite index on both order_ num and 
total-'price. 


• 
If the WHERE clause of a SELECT statement has a join 
condition between a single column in one table and a single 
column in another table, create an index on the column in 
the table with the larger number of rows. If several columns 
of one table have join conditions with several columns in 
another table, create a c;omposite index on the affected 
columns of the table with the larger number of rows. 
For the SELECT statement 


SELECT * FROM items, 
stock 
WHERE 
items.stock_num = stock.stock 
num 


place an index on stock_num in the items table, since it 
has many more rows than the stock table. You should 
execute the UPDATE STATISTICS statement before the 
SELECT statement so that RDSQL knows the current size of 
the tables. 
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For the statement 


SELECT 
• 
FROM items, 
stock 
WHERE 
items.stock__num 
stock.stock_num 
AND 
items.manu__code = stock.manu_code 


put a composite index on stock_num and manu_code 
the items table. 


Auto-Indexing 


If you execute a SELECT statement that includes a join 
between two tables and there are no indexes on the joined 
columns, RDSQL creates a temporary index on the table with the 
larger number of rows before performing the join. The index 
disappears when the query finishes. This enhancement is 
transparent to the user except for a dramatic improvement in 
the speed of unindexed joins. 


Clustered Indexes 


Since both UNIX systems and DOS systems extract informa- 
tion from the disk in blocks, the more rows that are physically 
on the same block and are already in the order of an index, the 
faster an indexed retrieval proceeds. Ordinarily, no relation- 
ship need exist between the physical order of the data in the 
.dat file and the order in an index. You can, at least tem- 
porarily, cause the physical order in the table to be the same as 
the ordering in an index through clustering. 


RDSQL orders, or clusters, the physical data in a table when you 
create a new index by executing a variant of the CREATE 
INDEX statement or when you execute the new ALTER 
INDEX statement for an existing index. Since users who have 
access to the table can add additional rows or update the infor- 
mation in existing rows, a table that you cluster according to an 
index does not stay that way. Over time, you can expect the 
benefit of an earlier clustering to disappear and you may want 
to cluster the table again using an ALTER INDEX TO 
CLUSTER statement. 
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Since a table can have only one physical order, you can 
have only one clustered index on a table at any given time. 
You can change the physical order to reflect a different index 
by executing two ALTER INDEX statements: 


1. Execute an ALTER INDEX TO NOT CLUSTER state- 
ment to release the cluster attribute from the first index. 


2. Execute an ALTER INDEX TO CLUSTER statement to 
attach the cluster attribute to the second index. 


You cannot execute the ALTER INDEX or CREATE INDEX 
statements on a view. 


Locking 


INFORMIX·4GL uses locking to prevent different users from exe- 
cuting conflicting operations on the same data. Without lock- 
ing' for example, two users may be allowed to update the same 
row at the same time. In this situation, the computer memory 
contains two different versions of the rows (the one updated by 
user A and the one updated by user B). Without some method 
of concurrency control, the user whose row is the last one actu- 
ally written to the file "wins" and overwrites the other user's 
changes. 


The following RDSQL statements are used to control locking: 


LOCK TABLE 
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limits access to the table to the current 
user only or allows other users only to 
read the table. Use the LOCK TABLE 
statement only when making major 
changes to a table in a multi-user 
environment and when simultaneous 
interaction with the table by another 
user would interfere. LOCK TABLE 
decreases the accessibility of the data- 
base, since it prevents other users from 
accessing the table. If the database has 
transactions, you must issue a BEGIN 
WORK statement before you can issue 
the LOCK TABLE statement. 


UNLOCK TABLE 
restores access to a previously LOCKed 
table. 


SET LOCK MODE alters the locking strategy either to fail 
when a row is already locked or to wait 
for the lock to be released before 
proceeding. 


In addition, in the rare instance where you need to limit access 
to the entire database to a single user, you can open the data- 
base in EXCLUSIVE mode. 


INFORMIX-4GL provides two levels of locking: 


• 
Row-level or record-level locking 
• 
Table-level or file-level locking 


RDSQL performs row-level locking implicitly. The locking stra- 
tegy may differ slightly, depending upon whether or not the 
database uses transaction management. Data definition state- 
ments, such as ALTER TABLE, CREATE INDEX, and so on, 
use implied table-level locking. You can explicitly specify 
table-level locking. The following sections describe each level 
of locking and the methods for its use. 


Row-Level Locking 


Ordinarily, RDSQL locks a row when you execute an UPDATE 
statement, or when you execute a FETCH statement and the 
cursor is DECLAREd with a FOR UPDATE clause. If the 
UPDATE statement affects only one row, RDSQL releases the 
lock immediately after performing the update. This prevents 
two programs from attempting to update the same record at 
the same time. One program receives the lock and can proceed 
with the update. The other program either fails in its attempt 
or waits for that program to release the lock. (See the section 
"Wait for Locked Row" later in this chapter.) 


Ifthe UPDATE statement affects more than one row, RDSQL 
uses the same row-locking strategy. As soon as it completes an 
update, it releases the lock, then locks and updates the next 
record. When the UPDATE finishes, all records are unlocked. 
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If you want more control over the update of multiple records, 
you can DECLARE a cursor FOR UPDATE. The WHERE 
clause of the SELECT statement spedfies the rows you want to 
update. After you OPEN the cursor and FETCH a record, that 
record remains locked until you either CLOSE the cursor or 
FETCH the next record. 


Row-Level Locking in Transactions 


If your database uses transaction management, rows that you 
INSERT, UPDATE or DELETE within a transaction remain 
locked until the end of the transaction. The end of a transac- 
tion is either a COMMIT WORK, where all modifications are 
made to the database, or a ROLLBACK WORK, where none 
of the modifications are made. 


RDSQL locks a row when it is selected for update. For 
example, if you DECLARE a cursor FOR UPDATE, the 
FETCH statement locks the row. The row remains locked 
until the end of the transaction. 


Table-Level Locking 


Use table-level locking to lock an entire table and prevent 
others from altering or seeing rows in that table. 


You may want to use this form of locking during batch 
operations that affect every row in a table, for example. If the 
operations must be completed as a single transaction, 
it may be more efficient to.lock the entire table at the begin- 
ning of the transaction. Normally, under transactions, 
INFORMIX-4GL locks each row as it is UPDATEd, DELETEd, or 
INSERTed. If you lock the entire table, however, 
INFORMIX-4GL does not use row-level locking because it is 
unnecessary. As a result, you are not likely to reach the limits 
that your operating system may place on the number of rows 
that can be locked at anyone time. 
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RDSQL performs table-level locking automatically as part of the 
following statements: ALTER TABLE, DROP TABLE, 
CREATE INDEX, ALTER INDEX, and DROP INDEX. 


The LOCK TABLE statement has two extensions: 


• 
If you lock the table IN SHARE MODE, other users are 
able to SELECT data from the table, but they are not able 
to INSERT, DELETE, or UPDATE rows in the table. 


• 
If you lock the table IN EXCLUSIVE MODE, other users 
are not able to access the table at all until you execute an 
UNLOCK TABLE statement. 


Because locking an entire table prevents others from adding or 
altering data in the table, use this feature sparingly. Lock the 
entire table only when row-level locking (as described in the 
previous section) is not sufficient. 


Wait for Locked Row 


If another user locks a row in a table at the row level and you 
attempt to alter or delete that row (or examine it with 
SELECT statement FOR UPDATE), RDSQL returns an error 
stating that the row is locked. If you prefer that RDSQL wait on 
any locked row until the competing process unlocks it, you can 
execute the SET LOCK MODE TO WAIT statement. From 
then on, your request waits until RDSQL unlocks the requested 
row, and you do not receive an error code. 


Caution! If for some reason the competing process fails without 
unlocking the row, your process deadlocks. Consequently, use the 
SET LOCK MODE statement with caution. 


If another user locks a table IN EXCLUSIVE MODE and you 
attempt to alter, to delete, or even to read a row in the table, 
RDSQL returns an error code. The wait-far-lock feature applies 
only on multi-user systems that support record-level locking. 


NULL Values 


The basic purpose of introducing NULL values in a database is 
to indicate when no value has been assigned to a particular 
column in a particular row of a table. Your reasons for not 
having assigned a value could iriclude not knowing the correct 
value or that no value yet exists. The NULL may also indicate 
that no value is appropriate for a given column because of the 
values that were entered into other columns. 


As an example, consider entering data for a bank customer who 
is requesting a loan. If the customer, Mr. Farthing, is not 
employed, the employer column in the client table will have 
no entry for this customer. This CHAR column will have the 
value NULL. The hire_date column is meaningless if 
Mr. Farthing is not employed. There is no appropriate date to 
enter; the value is NULL. 


Default Values 


In RDSQL the default value for a column is NULL. RDSQL 
makes a distinction for numeric values between zero and 
NULL and for character values between blanks and NULL. 
You do not need to know how RDSQL implements the value 
NULL to make use of it. 


By definition, type SERIAL columns can never contain the 
NULL value. Columns of type SERIAL always contain 
integers greater than or equal to one. 


You can insist that a column of any type not have NULL 
values by using the NOT NULL clause in the CREATE 
TABLE statement. RDSQL will prevent a NULL from being 
entered into any column that is declared NOT NULL. 


You cannot, however, use a NOT NULL clause in an ALTER 
TABLE statement when you add a new column. The reason is 
that RDSQL enters a NULL value into that column for all rows 
that already exist. 
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A column for which you create a unique index can have, at 
most, one NULL value. 


Note for Users with an 
RDSQL Version 1 Database: 


When no value is provided for a column entry in a row of a 
table in an RDSQL Version 1 database, RDSQL enters a blank for 
type CHAR columns, zeroes for numeric columns, and a ver.y 
large negative value for type DATE columns. Since zero could 
well be an acceptable value for a numeric column (for example, 
the value for a type MONEY column), there is no way to 
distinguish an unknown value from zero. 


To incorporate an existing RDSQL Version 1 database into 
INFORMIX-4GL programs, you must execute the dbupdate utility 
described in Appendix 1. (Appendix I also describes how you 
can avoid using NULL values.) 


The NULL in Expressions 


If any value that participates in an arithmetic expression is 
NULL. the value of the entire expression is NULL. For 
example, consider the following query: 


SELECT order_num, 
ship_charge/ship_weight 


FRQv1 orders 
WHERE order 
num 
1023 


If ship_weight is NULL because the order with number 1023 
is new and the shipping charge has not yet been determined, 
the value returned for ship_charge/ship_weight will also 
be NULL. 


The situation is different when you use one of the aggregate 
functions (see Chapter 7 for a description of the aggregate 
functions). COUNT(*) counts all rows, even if the value of 
every column in the row is NULL. COUNT(DISTINCT 
column-name), AVG, SUM, MAX, and MIN ignore rows with 
NULL values for the column in their argument and return the 
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appropriate value based on the rest of the rows. However. if a 
column contains only NULL values, then COUNT(DISTINCT 
column-name) returns zero, and the other four aggregate 
functions return NULL for that column. 


The NULL in Boolean Expressions 


In order to incorporate NULL values into Boolean expressions. 
it is necessary to enlarge the number of truth values from sim- 
ply true and false to include unknown. If one of the expressions 
of a Boolean expression is NULL, the truth value of the 
Boolean expression is unknown. For example, the Boolean 
expression, 


ship_charge/ship_weight 
< 5.0 


has the truth value unknown for the order in the previous 
example. 


If you combine Boolean expressions using the operators AND, 
OR, and NOT, the following tables give the resulting truth 
value (where T corresponds to true, F to false, and? to 
unknown). 


AND 
T 
F 
? 
OR 
T 
F 
? 
NOT 
- - - - - - - -- 
......... 


(USE 
ART 
USE 
ART USE 
ART)T 
T 
T 
T 
F 
F 
F 
F 
F 
F 
T 
F 
? 
F 
T 
? 
? 
F 
? 
? 
T 
? 
? 
? 
? 
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The NULL in WHERE Clauses 


If the Boolean expression in a WHERE clause evaluates to 
unknown for a particular row, RDSQL treats the search condition 
as not satisfied and does not select or modify that row. 


Consider this clause 


WHERE ship_charge/ship_weight 
< 5 
AND order 
num 
= 
1023 


The row where order_num = 1023 is the row where 
ship_weight is NULL. Since ship_weight is NULL, 
ship_charge/ship_weight is also NULL, and the truth 
value of ship_charge/ship_weight < 5 is unknown. Since 
order_num = 1023 is true, the preceding AND truth table 
states that the truth value of the entire search condition is 
unknown. Consequently, that row will not be chosen. If the 
search condition had used an OR in place of the AND, the 
search condition would be true. 


You can select (or reject) rows containing NULL values with a 
new type of search condition: 


coiumn IS [NOT] NULL 


You must use the keyword IS. It is not permitted to write the 
condition as follows. 


column = NULL 
column != NULL 
(Incorrect) 
(Incorrect) 
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If you perform a join between two tables using the WHERE 
clause. 


WHERE column1 = column2 


RDSQL will not select the rows where either column1 or 
column2 is NULL. In particular, no row will be returned if 
both column1 and column2 are NULL. This is merely a 
special case of the more general rule that Boolean expressions 
containing NULL values have an unknown truth value. 


Similarly, if a subquery returns a single NULL value, the 
search condition evaluates to unknown. 


The NULL in ORDER BY Clauses 


For the purpose of sorting rows using the ORDER BY clause, 
the NULL value is treated as being less than a non-NULL 
value. When the ordering is ASe, the NULL values come first; 
when the ordering is DESe, the NULL values come last. 


The NULL in GROUP BY Clauses 


RDSQL treats each row containing a NULL value in the column 
being GROUPed BY as in a separate group. This is consistent 
with the fact that each NULL value is really unknown. There 
is no reason to treat all NULL values as being the same. 
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The NULL Keyword in INSERT and UPDATE 
Statements 


When you execute the INSERT statement, RDSQL will insert 
the NULL value into all columns for which you do not provide 
a value or for all columns not listed explicitly. Since the 
value-list of the INSERT statement must be the same length 
as the column-list, you can use the keyword NULL to indicate 
that a column in column-list should be assigned a NULL value. 


INSERT 
INTO orders 
(order_num. 
order_date. 
customer_num) 
VALUES 
(0. 
NULL, 
123) 


All other columns in the orders table will be filled with NULL 
values. Similarly, you can use the NULL keyword to modify a 
column value when using the UPDATE statement. For a 
customer whose previous address required two address lines, 
but now requires only one, you would use the following entry: 


UPDATE 
customer 
SET 
address1 
"123 
New Street", 
address2 
NULL, 
city 
"Palo Alto". 
zipcode 
"94303" 


WiERE 
c u s tome r_n urn = 
134 
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Views 


Views are constructs on a database that allow you to do the 
following tasks: 


• 
Provide different users with different windows (called 
"views") on the data in the database. A single view may 
involve columns from different tables or may show values 
that are functions of the values from the columns. A view 
has a name and looks to a user as if it were a table. The 
user may query a view, for example, using the same syntax 
as though the view were a table in the database. 


• 
Limit access to sensitive data by allowing users to see only 
aggregate information. With the GRANT and REVOKE 
statements, you can prevent a user from seeing any salary 
data in a personnel table. With a view, you can allow the 
user to see average salaries in various groups, but still 
protect the individual salary data. 


• 
Permit users to update, insert, and to delete data in the 
database as though the data were organized as it appears in 
a view. You can also examine through a view the changes 
made in a real table of the database. 


Views are therefore dynamic windows into the database and are 
not static snapshots. They differ in this respect from a tem- 
porary table created by the INTO TEMP clause of a SELECT 
statement or the CREATE TEMP TABLE statement. Such 
temporary tables show you only the state of the database when 
the temporary table was created. 


Although views appear to be tables in the database, there are 
several important ways in which they differ. You cannot use a 
view in place of a table in a form specification file. You cannot 
create an index on a view. There are conditions under which 
you cannot update or modify the data perceived through a 
view. An obvious case occurs when the "column" seen in a 
view is really an expression generated from actual database 
tables. Generally speaking, there is no way to determine the 
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appropriate change in the underlying columns involved in such 
an expression if you want to change the value of the "column." 


The next sections describe how to create and delete views, how 
to query the database through views, how to modify the data- 
base through a view, and how to set up permissions for a view. 


Creating and Deleting Views 


You must use the CREATE VIEW statement to create a view. 
(See Chapter 7 for complete information about the CREATE 
VIEW statement.) 
A view is determined by a SELECT state- 
ment that returns the "table" that defines the view. You can- 
not use the UNION operator (see Chapter 7 for the definition 
of the UNION operator) in the definition of a view. The 
SELECT statement is stored in the sysviews system catalog. 
When you subsequently make reference to a view in another 
statement, RDSQL performs the defining SELECT statement in 
executing the new statement. 


You can use the same column names as in the underlying table 
for the view or you can assign new names. 'When a column in a 
view is the evaluation of an expression or is not unique 
(because, for example, you have included all the columns of a 
join, including the columns that define the join), you must 
supply new names. These column names are stored in 
syscolumns along with the column names of regular tables. 


You can delete a view by executing the DROP VIEW 
statement. When you drop a view, you also drop all views 
that were defined in terms of that view. 
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Querying Through Views 


You can make queries involving views exactly as though they 
were tables in the database. If possible, RDSQL first combines 
the view-defining SELECT statement with the query to create 
a new SELECT statement and then executes the new state- 
ment. Otherwise, it creates the view as a temporary table and 
applies the query to the table. RDSQL may detect errors during 
either of these phases. 


Modifying Through Views 


Like querying through views, you may use the INSERT, 
UPDATE, and DELETE statements with views. RDSQL com- 
bines the view-defining SELECT statement with the view- 
referring statement and then executes it. The following 
restrictions apply to modifying tables through a view: 


• 
You cannot modify the database through a view if the view 
definition involves joins, the GROUP BY clause, the DIS- 
TINCT keyword, or an aggregate function. If any of these 
features is present in the view definition, the creator of the 
view cannot execute INSERT, DELETE, or UPDATE 
statements on the view. You may, however, define a view 
using a subquery that refers to another table and can often 
circumvent the restriction on joins (see the section "Data 
Constraints Using Views," later in this chapter). 


• 
A view colu'mn may be UPDATEd only if it is derived 
directly from a table of the database and not as a result of 
an expression. Expression-derived columns are called 
"virtual" columns. You cannot INSERT rows through a 
view that contains virtual columns, although you may 
DELETE a row that contains a virtual column. 


• 
You may not execute the ALTER TABLE, CREATE 
INDEX, ALTER INDEX, or UPDATE STATISTICS 
statements on a view. You do receive the benefit of existing 
indexes on the underlying tables. 


2-66 Views 


You may use an INSERT statement on a view that shows only 
a portion of an underlying table. When you do so, the unmen- 
tioned columns of the underlying table will receive NULL 
values. If one of the unmentioned columns does not permit 
NULL values, RDSQL will not permit you to INSERT to the 
view. 


If you drop a column of an underlying table of a view that you 
have defined in terms of that column, RDSQL issues an error if 
you subsequently make reference (other than DROP VIEW) to 
the view. 


Unless you create the view with a WITH CHECK OPTION 
clause, it is possible to INSERT or UPDATE data into a data- 
base through a view that does not satisfy the limitations on the 
view. A row INSERTed or UPDATEd in this manner is no 
longer accessible through the view. For example, a view could 
be created that allows the user access only to customers from 
Palo Alto. If, when using the view, the user creates a new row 
with a customer from Menlo Park, the user cannot select the 
row through the view. If the city column on an existing row is 
UPDATEd to Menlo Park, the row disappears from the view. 
The WITH CHECK OPTION clause on the CREATE VIEW 
statement causes RDSQL to reject an UPDATE or INSERT that 
violates the restrictions of the view. 


You must be careful when you UPDATE a table through a view 
that may contain duplicate rows. Duplicate rows can occur in a 
view even if the underlying table has unique rows. If a view is. 
defined on the items table and contains only the columns 
order_num and total.-price, the view contains duplicate 
rows if two items from the same order have the same total 
price. If you put the cursor on one of the rows where 
total'-price = $1234.56 and update the total'-price to 
$1250.00 through the view, you have no way of knowing which 
item you have increased. 
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Privileges with Views 


When you create a view, you receive the same privileges that 
you had on the underlying tables. If you have these privileges 
with the GRANT OPTION (see Chapter 7), you may grant 
privileges on your view to other users. 


If the view is built on more than one table, you can have only 
the SELECT privilege since multi-table views do not permit 
you to INSERT, DELETE, or UPDATE. You must have the 
SELECT privilege on all of the columns from which a multi- 
table view is derived to have the SELECT privilege on the 
entire view. If, as a result of these restrictions, you have no 
privileges on a view, the CREATE VIEW statement returnsan 
error code. 


Data Constraints Using Views 


The purpose of data constraints is to ensure that all data 
entered into the database satisfies pre-assigned limitations. 
Through a form in INFORMIX-4GL, data entry can be controlled 
with the INCLUDE attribute that lists yalues and ranges of 
values permitted for a column. The values entered into the 
syscolval table in the include column serve a similar purpose 
(see Chapter 3). In both of these cases, however, the list of 
allowed values is static and is dependent only on the designated 
column. 


It is often desirable to define allowed value ranges dynamically, 
based on the values in other columns or even in other tables. 
The existence of views and, specifically, the \VITH CHECK 
OPTION clause permits the DBA to control the entry of data 
into the database. This is most easily demonstrated with an 
example taken from the stores database. 
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Suppose you want to ensure that no item 


• 
Has a value of more than $20,000 
• 
Is for stock that does not exist 


The first step is to create the following view: 


CREATE VIBN safe 
items 
AS 
SELECT 
• 
FROM-items 


\\+JERE 
tot a I-'p rice < 20000 
AND 
EXISTS 
(SELECT stock_num. 
manu_code 
FROM stock 
\\+JERE stock.stock_num 
items.stock_num 
AND stock.manu_code 
items .manu_code) 
WITH CHECK OPTION 


If you do all data entry and data modification through the 
safe_items view, RDSQL will reject all data that does not meet 
the requirements of the WHERE clause. Because of the 
dynamic nature of views, the view will only contain rows 
corresponding to current stock items if you change the stock 
table by adding rows corresponding to new stock items or 
deleting old ones. 


By extending the WHERE clause, this example can be 
expanded to cover very general data-constraint needs. 
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Outer Joins 


An outer join between two tables treats the two tables unsym- 
metrically. One of the tables is dominant (often referred to as 
"preserved"), and the other table is subservient. If the subser- 
vient table has no rows satisfying the join condition, the outer 
join attaches a row of NULL values to the row of the dominant 
table before projecting the desired columns. To illustrate, let a 
be a column from tab! and b a column in tab2. Further, let 
the values in the two tables be as shown in the following 
display: 


tabl.a 
tab2.b 


2 
4 
3 
2 
5 
6 
5 


RDSQL syntax requires that the subservient table in an outer 
join be preceded by the keyword OUTER in the FRO!\1 clause. 
The following SELECT statement contains an outer join 
between tab! (the dominant table) and tab2 (the subservient 
table): 


select 
a, 
b 
from tab1, 
outer 
tab2 
where 
a = b 


The resulting table has the following two columns: 


a 


2 
3 
5 


b 


2 


5 


Every value for a is present and only those values of b that 
match those in a. When there is no value in column b that 
satisfies the join condition, a NULL value (shown here as -) is 
substituted. 
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A WHERE clause is required in the case of outer joins and 
must set a condition between the two tables. 


See Chapter 7 and Appendix L for more information about 
outer joins. 


Table Access by Row ID 


The keyword ROWID can be used in RDSQL statements to refer 
to the C·ISAM record number associated with a row in a data- 
base table. ROWID can be thought of as a hidden column in 
every table. When you refer to table.*, the implied list of 
columns does not include ROWID. 
On the other hand, you can use the syntax 


SELECT 
RONI 0, 
• 
FROv1 table 


to get the ROWID value for each row. You may also determine 
the ROWID of the last row that RDSQL dealt with by examining 
the SQLCA record. See the next section for how to do this. 


ROWID can also be used in WHERE clauses to select rows 
based on their C-ISAM record number. This feature is useful 
when there is no other unique column in a table. 


If a row is deleted from the table, its ROWID may be assigned 
to a new row. You should not attribute chronological or other 
significance to the sequential values of ROWID. 
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SQLCA Record 


Proper database management requires that all logical sequences 
of statements that modify the database continue successfully to 
completion. If, for example, you UPDATE a customer account 
to show a reduction of $100 in the payable balance and the 
next step, to UPDATE the cash balance, fails for some reason, 
your books will be out of balance. It is prudent to check that 
every RDSQL statement executes as you anticipated. 


I:!\'FORMIX-4GL provides two ways to do this: the global variable 
status that indicates errors both from form-related statements 
and RDSQL statements and a global record SQLCA that allows 
you to test the success of RDSQL statements. status provides 
the primary information; SQLCA provides additional 
information. 


RDSQL returns a result code into the SQLCA record after 
executing every RDSQL statement except DECLARE. This 
record is shown here: 


DEFI:!\E SQLCA RECORD 
SQLCODE 
INTEGER, 
SQLERRM 
CHAR(71), 
SQLERRP 
CHAR(S). 
SQLERRD 
ARRAY[6] OF INTEGER, 
SQLAWAR1\' 
CHAR(S) 
END RECORD 


SQLCODE 
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indicates the result of executing an RDSQL 
statement. It is set to zero for a successful 
execution of most statements and to NOT- 
FOUND (= 100) for a successfully executed 
query that returns zero rows or for a FETCH 
that seeks beyond the end of an active set. 


SQLCODE is negative for an unsuccessful 
execution. 


( 
\ 
. 


SQLERRM 


SQLERRP 


SQLERRD 


INFORMIX·4GL sets the global variable status 
equal to SQLCODE after each RDSQL state- 
ment. See the section "Error Messages" after 
the appendixes for the error codes. 


not used at this time 


not used at this time 


an array of six variables of type INTEGER 


SQLERRD[l] 


SQLERRD[2] 


SQLERRD[3] 


SQLERRD[4] 


SQLERRD[5] 


SQLERRD[6] 


not used at this time 


SERIAL value returned 
or ISAM error code 


the number of rows 
processed 


the estimated CPU cost 
for query 


offset of error into the 
RDSQL statement 


ROWID of last row 


SQLAWARN 
is a character string of length eight whose 
individual characters signal various warning 
conditions (as opposed to errors) following the 
execution of an RDSQL statement. The 
characters are blank if no problems were 
detected. 


\. 


SQLAWARN[l] 
is set to W if one or 
more of the other 
warning characters 
has been set to W. If 
SQLAWARN[l] is 
blank, you do not han: 
to check the remaining 
warning characters. 


2-73 


2-74 SQLCA Record 


SQLAWARN[2] 


SQLAWARN[3] 


SQLAWARN[4] 


SQLAWARN[5] 


SQLAWARN[6] 


SQLAWARN[7] 


SQLAWARN[8] 


is set to W if one or 
more data items was 
truncated to fit into a 
CHAR program variable. 


is set to W if an aggre- 
gate function (SUM, 
AVG, MAX, or MIN) 
encountered a NULL 
value in its evaluation. 


is set to W when the 
number of items in the 
select-list of a SELECT 
clause is not the same as 
the number of program 
variables in the INTO 
clause. The number of 
values returned by RDSQL 
is the smaller of these 
two numbers. 


is not used at present. 


is not used at present. 


is not used at present. 


is not used at present. 


TODAY and USER Functions 


RDSQL provides functions to allow you to include the date and 
the user's name in a statement. TODAY always returns the 
system date. USER returns a string containing the current 
user's name. On UNIX systems, this is the login name; on 
multi-user DOS systems, this is the machine name. 
The USER function returns the constant pcuser on 
single-user DOS systems. 


You can use these functions wherever you use a constant. For 
example, if you wish to retrieve the rows that you have inserted 
into a table, you must define a column to contain the USER 
name. When you insert into the table, use the USER function 
as follows: 


INSERT 
INTO 
~bk VALUES 
( ... ,USER, ... ) 


You can then retrieve the rows that you entered with a select 
statement, as follows: 


SELECT 
• 
FROv1 table 


w-iERE user_col = USER 


(See the section "Cursor Management" earlier in this chapter 
for a discussion on using the SELECT statement to return 
multiple rows.) 


Use the TODAY function in the same way. You can insert the 
system date into a table with the following statement: 


I NSERT 
I NTO table 
VALUES 
( ... , 
TODAY, 
... ) 


Use the next statement to retrieve all rows with today's date 
from a table: 


SELECT 
• 
FROv1 table 


w-iERE date_col = TODAY 
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Chapter Overview 


Before you can use a customized screen form in your 
I:'\'FORMIX-4GL program, you must create a form specification 
file and use FORM4GL to compile this file. The form 
specification file contains the screen format and the 
instructions to I:'\'FORMIX-4GL about hO\\' to display the data. 


This chapter describes the syntax and compilation procedure 
for form specification files. It also describes the syscolval and 
syscolatt tables into which you can insert default attributes, 
formats, and values for your screen fields. 


Note: 
The FORM4GL syntax for forms that you design to work 
with Il'\FORMIX-4GL is different in several significant ways from 
the syntax you use to design a screen for the screen transaction 
program PERFORM, in INFORMIX-SQL. PERFORM forms can be 
used with INFORl\IIX-4GL, but you must recompile them using 
FOR:\14GL. (See the section "Creating and Compiling a Form" 
later in this Chapter for information about using FORM4GL.) 
In 
addition, not all the PERFORM features are operative. The sec- 
tion "Using PERFORM Forms in INFORMIX-4GL" at the end 
of this chapter describes the effect of using forms designed for 
PERFOR:\1 in INFORMIX-4GL programs. 
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Structure of a Form Specification File· 


Form specification filesconsist of three required sections 
(Database, Screen, and Attributes) and two optional sections 
(Tables and Instructions): 


• 
Database Section: Each form specification file must begin 
with a Database section identifying the database (if any) on 
which you want to base the form. 


• 
Screen Section: The Screen section appears next and 
shows the exact layout of the form as you want it to appear 
on the screen. 


• 
Tables Section: Each form specification file must contain a 
Tables section following the Screen section if you define any 
field with the name of a column. The Tables section 
identifies the tables whose columns will determine the fields 
that appear in the form. 


• 
Attributes Section: The Attributes section describes each 
field on the form-including, for example, appearance. 
acceptable input values, on-screen comments, and default 
values. 


• 
Instructions Section: The Instructions section is optional 
and specifies alternate field delimiters and defines screen 
records and screen arrays. 
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The following figure illustrates the overall structure of form 
specification files: 


DATABASE 
stores 


SCRE EN 


CUSTOMER 
INFORMATION 
C us t orne r 
Numb e r; 
. C , 


SHIPPING 
INFORMATION 
CustomEr 
P 0 
020 


Sh:p 
Date 
021 


TABLES 
C U5 I orne r 
0 r de r S 
I I ems 
ma n u f act 


ATTRIBUTES 
c, = 
c U 5 t orne r 
C L.' S I orne r ..n urn 
= orders 
cusl0mer_"um, 


Telephone 
:C1C 


Dale 
Paid 
'022 


Cl0 = customer 
phone. 
PICTURE 
= 
"~=~-##=-:==#x===r~1 


020 
orders 
p~ nurn 
021 = orders 
shIp dale. 
022 = orders paid dale, 


INS TRLlCT IONS 
SCREEN 
RECORD 
sc_order 
5 
(orders 
order_date 
THRU 
orders 
pSld_.date) 


Figure 3-1. Schematic for a Form File 


Database Section 


The Database section of a form specification file identifies the 
database with which the form is designed to work. 


The Database section consists of the DATABASE keyword 
followed by the name of the database. The structure of the 
DATABASE section is as follows: 


DATABASE 
database·name [WITHOUT NULL INPUT] 


Notes 


1. The WITHOUT NULL INPUT option should be used only 


if you have elected to create and work with a database that 
does not have NULL values (see Appendix I for the other 
required steps). The effect of this option is to cause 
Il\"FORMIX-4GL to display as defaults zeros for numeric and 
DATE fields and blanks for CHAR fields that have no other 
defaults. 


2. 
It is possible to create a form that is not related to a data- 
base. To do so, give the database name as formonly and 
omit the Tables section of the form specification. Use the 
table name formonly in the Attributes section in naming 
the fields. 


Examples 


database 
stores 


Screen Section 


The Screen section of the form specification file describes how 
the form will appear on the screen when you use it with 


Il\"FORMIX-4GL. It begins with the keyword SCREEN and is 
optionally terminated with the END keyword. 


Page Layout 


A page layout consists of an array of displa.y fields and textual 
information such as titles and field labels. 
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Syntax 


SCREEN 


display 
fields 
and 
text 


~END 


Explanation 


page 
layout 


SCREEN 


I 
I 
I 
I 


END 


Notes 


is a required keyword. 


are required symbols indicating the beginning and 
ending of the page layout. 


is an optional keyword. 


1. Do not include more than twenty screen lines bet\veen the 
pair of braces. If you do. FORM4GL will split the page into 
two, with the twenty-first line at the top of the second page. 
You cannot use multiple-screen forms with INFOR:\HX-4GL. 


2. Form specification: files basedon earlier RDS products use 
the END keyword in the Screen section. The IJ.VFORMIX- 
4GL User Guide follows this practice. 
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Display Fields 


Indicate where data is to be displayed on the screen by using 
brackets [ ] to delimit a field. Each field has an associated field 
tag that identifies the field in the Attributes section. 


Syntax 


ltic/dlat! 


Explanation 


[ ] 


fieldtag 


Notes 


are delimiters for a field. The width of the field 
is the number of characters that can be placed 
between the brackets. In this context. the 
brackets are required and do not 
signif~' an 
optional syntax. 


is the field tag used to identify the display field. 


1. 
Each field must have a field tag. 


2. 
The field tag is from one to fifty characters long. The 
first character must be a letter; the rest of the tag may 
include letters, numbers. and underscores (_). The field 
tag must fit within the brackets. 


3. 
The same field tag can be used at more than one position 
in the Screen section of the form specification if you want 
the same column information to appear at more than one 
place or if you define a screen array (see "Instructions 
Section"). 


4. 
Field tags are labels and are not the same as field names. 
The Attributes section links each field tag to a field name. 
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5. 
FOR;\14GL ignores the case of a field tag: al and Al are 
the same. 


6. 
One-character columns are given the display tags a 
through z. This means that a screen form can use no 
more than twenty-six one-character columns. 


I. 
\\'he11 you create a default form specification file (see 
"Creating and Compiling a Form"), the widths of all fields 
are determined by the data type of the corresponding 
columns in the database tables. 


8. 
If you create your own form, you will normally want the 
width of a field in the screen section ofthe form 
specification to be equal to the width of the program 
variable or column to which it corresponds. 


9. 
Fields corresponding to numeric columns should be large 
enough to contain the largest number that you might 
display. If the field is too small to display the number 
that you assign, INFORMIX·4GL fills the field with asterisks. 


10. 
Fields intended to display CHAR type data can be shorter 
than acolumn's defined length. IXFORMIX·4GL will fill the 
field from the left and truncate the right end of any 
CHAR string that is longer than the field to which it is 
assigned. Through subscripting. you may assign portions 
of a CHAR column to one or more fields (see "Attributes 
Section," later in this chapter). 


11. 
If you edit and modify the default form specification file 
or create one from scratch, you can verify that the field 
widths match the width requirements of the correspond- 
ing CHAR columns by using the -v option OfFOR;\14GL. 
In response to the system prompt, enter 


form4g1 -v form-name 


FORM4GL reports any discrepancies in the file 
form-name.err. 
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Examples 


The following is a screen layout from the orderform.per form 
specification file in the INFORMIX-4GL demonstration program. 


SCREEN 


ORDER 
FOff>l 


Customer 
Number.: 1000 
Company Name: t003 
Address: 1004 
Ci Iy:. t006 
Te t ephone: : t008 


Contact 
Name: 
fOOl 
.1002 


: 1005 
S!ate 
80: 
Zip Code. f007 


Order 
No:· 1009 
. 
Order 
Date:' 1010 
ShipP'Fng 
Instruct;ons::f012 
. 
Purchase Order 
No:: fOl1 


I t em 
No 
: 1013 
: to 13 
: f 0' 3 
: f 0 13 


END 


Stock 
·1014 
.1014 
: fa 14 
: f 0 14 


No 
Code 
Oeser ip1 ion 
: a 1 
. f 0 15 


. a 1 
. fa 15 
. a 1 
: f 0'5 
: a 1 
. 1015 
Running Total 
including 
Tax 


QuantIty 
Price 
. 1016 
.. f 0 17 


f 0 16 
: f 0 17 
f 0 16 
. to i 7 


f 0 16 
. f 0' 7 
nd Shipping Charges 


Tables Section 


Overview 


The third section of the form specification file lists all the 
tables whose columns appear in the screen form. 
You need not 
display every column of every table listed. 
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The Tables section consists of the TABLES keyword, followed 
by a table name or a list of table names from the database 
named in the Database section. You may list up to fourteen 
tables separated by spaces or commas. The structure of the 
TABLES section is shown below. 


TABLES 
table-name 


[EKD] 


Notes 


1. The END keyword is optional. 


2. You do not need to include a Tables section if you have 


specified FORMONLY in the Database section of a form 
specification file. 


Examples 


The Tables section from the orderform form specification file 
in Appendix A is as follows: 


TABLES 
customer 
orders 
items 
stock 
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Attributes Section 


Overview 


The Attributes section describes the beha\'ior and appearance 
of each field in the Screen section and associates each field 
with a field name. Every field in the Screen section must be 
described in the Attributes section. You use attributes to 
describe how IXFOR:\IIX-4GL should display the field. to specify 
a default value. to limit the values that may be entered. and 
to set other parameters as described later in the section 
"Attributes Syntax." The general format of the Attributes 
Section is 


ATTRIBUTES 


field-tag = field-description: 


[E::\D] 


Notes 


1. The order in which the fields are described in the Attributes 
section determines the order for the fields in the default 
screen records (see "Instructions Section"). 


2. The END keyword is optional: however. earlier RDS 
products required it. The INFORMIX-4GL L'ser Guide 
follows the earlier format. 


3. 
Fields in the Screen section do not have to be associated 
with a column from the database. A field not associated 
with a column is called a form-only field. 


The Attributes section contains two kinds of field descriptions: 
those linking field tags to database columns and those linking 
field tags to form-only fields. 
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Fields Linked to Database Columns 


Screen fields are associated with database column:.:. only during 
the compilatiOIl of the form specification file. 
During the com- 
pilation process. FOR:\14GL examines two optional tables. 
syscolval and syscolatt. for default values of the attributes 
that you haw associated with columns of the database (see the 
section "Default Screen Attributes:' later in this chapter. for a 
discussion of these tables). After extracting these default attri- 
butes and obtaining the data type from the system catalog~. thE' 
association between the fields and database columns is broken. 
You must mediate between screen fields and database columns 
with program variables. 


Syntax 


field-tag = [tah!r.]co/umn[. attr-list]: 


Explanation 


field-tag 
is a field tag that identifies a field in the Screen 
section. 


table 
is the name of a database table listed in the Tables 
Section. 


column 
is the name of a column in table or. if table is not 
gi\"en. in one of the tables listed i11 the Tables 
section. 


attr-list 
is one or more FORM4GL attributes. separated by 
commas. 


Notes 


1. Only the field tag, the equal sign. the column name, and the 
semicolon are required. 
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2. 
You need to specify table only if column occurs in more 
than one table in the form. FORM4GL issues an error during 
compilation if there is ambiguity. Because you will often 
refer to field names collectively through a screen record (see 
"Instructions Section") built upon all the fields related to a 
single table. you may find your specification files easier to 
work with if you specify table for each field. 


3. 
You can display a portion of a CHAR type column in a 
field by using subscripting. For example, the orders table 
has a ship_instruct column that is a CHAR type column 
of length 40. You can display the first portion of 
ship_instruct on the screen as a field of length 20. 
Because you cannot use subscripts in the field-name list in 
an I~FORMIX-4GLINPUT, INPUT ARRAY, DISPLAY, or 
DISPLAY ARRAY statement, you must use form-only fiefds 
(described in the next section) to handle the second portion 
in data entry and display. If the field tags for the two fields 
are instl and inst2, respectively, the Attributes section 
entry is as follows: 


ins t 1 
inst2 
or de r s . s h i p_ins t rue t : 1 . 20: ; 
FORMONLY.ship_in2; 


In this case, the default screen record orders.* does not 
have a component corresponding to inst2. 


Form-Only Fields 


Form-only fields are not associated with columns of the data- 
base. They can be used to display information on the screen 
and to retrieve data from the screen. 


Syntax 


fieldtag = FORMONLY.field-name 
[TYPE [data-type I LIKE table.column]J[?\'OT l\'CLL] [. attr-li.<t]: 
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Explanation 


field-tag 


FORr-.l0NLY 


field-name 


TYPE 


data-type 


LIKE 


table. column 


NOT NULL 


attr-list 


Notes 


is the field tag used in the SCREEN 
section. 


is the ke).rword indicating that the field does 
not correspond to a column of a table in 
the database. 


is an RDSQL identifier for the name of the 
field. 


is an optional keyword. 


is anyone of the data types permitted by 
RDSQL except SERIAL (see Chapter 2 for 
the definition of the data types). 


is an optional keyword. 


is the name of a column in the database. 


are optional keywords informing 
INFORMIX-4GL that, if you name this field in 
an INPUT or INPUT ARRAY statement. 
the user must give it a value. 


is a list of one or more attributes separated 
by commas. 


1. You must give a value for data-type only when you want t(l 


use the INCLUDE or DEFAULT attribute for this entry. 
Otherwise, FORM4GL assumes the field is a CHAR field 
whose length is the width of the field. INFORMIX-4GL 
performs the necessary data conversion for the 
corresponding program variable during input or display. 
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2. 
When describing data-type, do not give a length to type 
CHAR. DECIMAL or MONEY; the length is determined 
by the display width. 


3. When you specify one or more form-only fields. 


IXFORMIX-4GL behaves as though these fields formed a 
database table named formonly. with the field names as 
column names. 


4. 
When the Database section has the WITHOCT NULL 
INPUT clause, the NOT NULL keyword instructs 
IXFORMIX·4GL to use zero (numeric type) or blanks (CHAR 
type) as a default for this field in INPUT or INPUT 
ARRAY statements. If you do not specify the type. 
Il"FORMIX-4GL treats the field as type CHAR. 


Examples 


The following form-only fields could be used in an order entry 
form to display information about items: 


f020 
formonly.manu_name; 
f021 
formonly.description; 
f022 
formonIY.unit-----'price; 


1023 
formonly.unit_descr; 


The demonstration application uses the following form-only 
field to store the running total price for the order as items are 
entered: 


f019 
= 
formonly.t-----'price 
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Multiple-Column Fields 


A screen fbrm that contains information from several database 
tables may include screen fields that you will use to display 
data via program variables from two (or more) database 
columns. 


The database columns you assign to the same field must haye 
the same field size. Usually. they will have the same data 
t~·pe. 


If they are CHAR columns, they must have the same length. 


You assign columns to the same field tag in the Attributes 
section: 


field· tag = tahld.column = table2.column: 


The placement of attributes determines when they take effect. 
When IXFOR::\HX-4GL executes an INPUT, INPl1T ARRAY, 
DISPLAY, or DISPLAY ARRAY statement. the screen fields 
listed (explicitly or implicitly) in the statement are called active 
fields. If you want an attribute to apply regardless of which 
field name is active, place the attribute after the last field 
name: 


field·tag = tableJ.column = tablc2.column. attr-list: 
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If you want different attributes to apply for each of the field 
names. place a semicolon after the attribute list for the first 
field name: 


field-taR = tablel.column. attr-list1; 
= 
tablc2.column. attr-list2: 


attr-list} is effective when table}.column is active, and attr-list2 
is effective when table2.column is active. 


The FORMAT and REVERSE attributes, described later in 
this chapter, always take effect, regardless of their placement. 


Attributes Syntax 


FOR;\I4GL recognizes the attributes listed below. The syntax for 
each attribute is detailed in the following sections. 


AUTONEXT 
COMMENTS 
DEFAULT 
DISPLAY LIKE 
DOWNSHIFT 
FOR\lAT 
INCLUDE 
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NOENTRY 
PICTURE 
REQl'IRED 
REVERSE 
l'PSHIFT 
VALIDATE LIKE 
VERIFY 


AUTONEXT 


Overview 


Use the AUTONEXT attribute to cause the cursor to adyan('(- 
automatically during input to the next field when the current 
field is full. 


Syntax 


field-tag = table.column. AUTO:t\EXT: 


Explanation 


field-tag 
is the field tag used in the Screen sectiun. 


table.column 
is the name of a field (either related to a 
column or form-only). 


AVTO~EXT 
is a keyword that tells IXFOR:\IlX·4GL to 
advance the cursor to the next field when the 
current field is full. 


Notes 


1. You specify the order of fields in each INPUT or INPUT 
ARRAY statement. 


2. AUTONEXT is particularly useful with CHAR fields in 
which the input data is of a standard length (a zip code 
column always requires five digits, and the abbreviation for 
a state is always two letters), or when the CHAR field has a 
length of one (only one keystroke is required to enter thf 
data and to move to the next field), 
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3. If the data entered into the field does not meet the require- 
ments of other attributes like INCLUDE or PICTLTRE. the 
cursor does not automatically move to the next field. but 
remains in the current field. 


Examples 


The demonstration application uses the customer form to 
enter all the names and addresses of the customers. The fol- 
lowing excerpt from the Attributes section of the customer 
form uses the AUTONEXT attribute: 


aD = customer.state, 
DEFAULT = "CA", 
AUTONEXT; 
f007 
customer.zipcode, 
AUTONEXT; 
f008 = customer.phone; 


When two characters are entered into the customer.state field 
(thus filling the field), the cursor mO\Oes automatically to the 
beginning of the next field (the customer.zipcode field). 
\Vhen five characters are entered into the customer.zipcode 
field (filling this field), the cursor moves automatically to the 
beginning of the next field (the customer.phone field). 
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COMMENTS 


Overview 


ese COl\lMENTS to cause I~FOR~IIX-4GL to display a message 
on the Comment Line at the bottom of the screen. The mes- 
sage is displayed when the cursor moves to the associated field 
and is erased when the cursor mm-es to another field. 


Syntax 


field-tag = table.column, COMMENTS = "message": 


Explanation 


field-tag 
is the field tag used in the Screen section. 


tob/e.co/umn 
is the name of a field (either related to a 
column or form-only). 


COMMENTS 
is a required keyword. 


message 
is a character string enclosed in quotat ion 
marks. 


Notes 


1. The message must appear in quotation marks on a single 
line of the form specification file. 


2. The default position of the Comment Line on the screen is 
line 23. You can reset this position with the OPTIONS 
statement. 


3. The default position of the Comment Line in a window is 


LAST. You can reset this position in the OPTIONS state- 
ment (if you want the new position in all windows) or in the 


~-::n 


ATTRIBUTE clause of the appropriate OPEN WINDOW 
statement (if you want the new position in a specific 
window). 


4. The most common application of the COMI\1ENTS 


attribute is to give information or instructions to the user. 
This is particularly appropriate when the field acceptsonl~' 
a limited set of values. 


Examples 


c2 = 
fname, 
comments = 
"p I e as e 
en t e r 
i nit i a I 
i f 
a v a i I a b Ie. " ; 
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DEFAULT 


Overview 


l;se the DEFACLT attribute to assign a default \'aluE' t(1 a 
display field. 


Syntax 


/il'id-ta,!! = tahlr.column. DEFAllLT = L'alur: 


Explanation 


field- to~ 


table.column 


DEFAULT 


L'aIu(' 


Notes 


is the field tag used in the Screen senion. 


is the name of a field (either related to a 
column or form-only). 


is a required keyword. 


is the default value. 


1. 
Default values have no effect when you execute the INPUT 
statement using the WITHOUT DEFAULTS option. In 
this case, I:\,FORMIX·4GL displays the values in the program 
variables list on the screen. The situation is the same for 
the II\PCT ARRAY statement except that I:\'FOR~iIX--!GL 
displays the default values when you insert a new row. 


2. If you use the WITHOUT NULL INPUT option in the 
Database section and you do not use the DEFAULT attri- 
bute. CHAR and DATE fields default to blanks, numerie 
fields to 0, and money fields to $0.00. 


.") 
,-.- 
.)-.,:... 


3. If you do not use the \VITHOUT NULL INPUT option in 
the Database section, all fields default to NULL values 
unless you use the DEFAULT attribute. 


4. If the field type is CHAR or DATE. enclose value in 
quotation marks. 


5. If both the DEFAULT attribute and the REQUIRED 
attribute are assigned to the same field, the REQUIRED 
attribute is ignored. 


6. Use the TODAY key\\'ord as the ualue to assign the current 
date as the default value of a field. 


Examples 


c8 = state. 
UPSHIFT. 
AUTONEXT. 
DEFAULT = "CA"; 


012 = order_date. 
DEFAULT = TODAY; 
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DISPLAY LIKE 


Overview 


Use the DISPLAY LIKE attribute to cause IXFORI\IIX-4GL to 
display the ,field using the attributes assigned to a database 
column in the syscolatt table. 


Syntax 


field-tag = table.column, DISPLAY LIKE tbl.col; 


Explanation 


field-tag 


table. column 


DISPLAY LIKE 


tbl.col 


Notes 


is the field tag used in the Screen section. 


is the name of a field (either related to a 
column or form-only). 


are required keyvlOrds. 


is the name of a column in the database. 


1. This attribute is equivalent to listing all the attributes that 
you have assigned to tbl.eol in the syscolatt table. See the 
section "Default Screen Attributes" for details on the 
syscolatt table. 


2. You do not need the DISPLAY LIKE attribute if 
table.eolumn is the same as tbl.eol. 
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Examples 


s12 
formonly.total, 
DISPLAY 
LIKE 
items.totaIJrice: 


Related Attributes 


VALIDATE LIKE 
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( 


DOWNSHIFT 


Overview 


Assign the DOWNSHIFT attribute to a CHAR field when YCYJ 
want I~FORMIX-4GLto convert uppercase letters entered by thE: 
user to lowercase letters, both on the screen and in the 
corresponding program variable. 


Syntax 


field-tag = table. column, DOWNSHIFT; 


Explanation 


field-tag 


table.column 


is the field tag used in the SCREEN section. 


is the name of a database column. 


DOWNSHIFT 
is the keyword that instructs I~FOR;\UX-4GLto 
convert CHAR input data to lowercase letters 
in the program variable. 


Notes 


1. Because uppercase and lowercase letters have different 
ASCII values, storing character strings in one or the other 
format can simplify sorting and querying a database. 


Related Attributes 


UPSHIFT 
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FORMAT 


Overview 


Use the FORMAT attribute with a DECIMAL, SMALL- 
FLOAT, FLOAT, or DATE column to control the format of 
the display. 


Syntax 


field-tag = table.column, FORMAT = "format-string"; 


Explanation 


field-tag 
is the field tag used in the Screen section. 


table.column 
is the name of a field (either related to a 
column or form-only). 


FORMAT 
is a required keyword. 


format-string 
is a string of characters that specifies the 
desired data format. You must enclose 
format-string in quotation marks. 


Notes 


1. For DECIMAL, SMALLFLOAT, or FLOAT data types, 
format-string consists of pound signs (#) that represent 
digits and a decimal point. For example, "###.##" produces 
at least three places to the left of the decimal point and 
exactly two to the right. 


2. If the actual displayed number is shorter than the format- 
string, I~FORMIX-4GLright-justifies it and pads the left with 
blanks. 
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3. If the format-string is smaller than the display width. 
FORM4GL gives a warning, but the form is usable. 
INFORMIX-4GL displays the data right-justified in the field. 


4. If necessary to satisfy the format, INFORMIX-4GL rounds 
numbers before displaying them. 


5. For DATE data types, INFORMIX-4GL recognizes the 
following symbols as special in the string format-string: 


mm 


mmm 


dd 


ddd 


yy 


yyyy 


produces the two-digit representation of the 
month. 


produces a three-letter abbreviation of the 
month, for example, Jan, Feb, and so on. 


produces the two-digit representation of the day. 


produces a three-letter abbre\'iation of the day of 
the week, for example, Mon, Tue, and so on. 


produces the two-digit representation of the year. 


produces a four-digit year. 


For dates, FORM4GL interprets any other characters as 
literals and displays them wherever you place them within 
format -string. 
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Examples 


For DATE fields: 


Input 


no FOR\IAT attribute 
FOR\fAT = "mm/dd/yy" 
FORMAT = "mmm dd. yyyy" 
FORMAT = "yymmdd" 
FOR.\lAT = "dd-mm-Yv" 
FOH\lAT = "(ddd.) ~;nm. dd. yyyy" 


Related Attributes 


PICTURE 
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Result 


09/15/1986 
09/15/86 
Sep 15. 1986 
860915 
15-09-86 
(Sat.) Sep. 15. 1986 


INCLUDE 


Overview 


Use the INCLUDE attribute to specify acceptable values for a 
field and to cause INFORMIX-4GL to check before accepting an 
input value. 


Syntax 


field-tag = table.column, INCLUDE = (value-list); 


Explanation 


field-tag 


table.column 


INCLUDE 


L'alue-list 


Notes 


is the field tag used in the Screen section. 


is the name of a field (either related to a 
column or form-only). 


is a required keyword. 


is either a list of individual values (value1, 
L'alue2, ...) or a range of values (value1 TO 
value2) or a combination of individual values 
and ranges separated by commas. 


1. When you specify a range of values, the lower value must 
appear first. 
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2. For ranges of character values, INFORMIX-4GL uses dictionary 
ordering with the printable ASCII character set (see 
Appendix M for an ordered list of the ASCII character set). 
In a numeric field, the range 5 TO 10 is acceptable. 
In a 
CHAR 'field, it is incorrect. The character string"10" is less 
than the string "5," since 1 comes before 5 in the ASCII 
character set. 


3. If you include a character string that contains a blank 
space, a comma, or any special characters, or does not begin 
with a letter, you must enclose the entire string in quotation 
marks. It is advisable to enclose character strings in 
quotation marks at all times. 


4. 
Before INFORMIX-4GL accepts a new row, you must enter an 
acceptable value in each display field with the INCLUDE 
attribute. If the list of acceptable values in the value-list 
does not include the default value, the INCLUDE attribute 
behaves like the REQUIRED attribute, and an acceptable 
entry is required. 


5. Including a COMMENTS attribute indicating acceptable 
values makes data entry easier. 


Examples 


i 18 = items,quant ity, 
include 
= 
(1 
to 50), 
comments = "Acceptable values are 
1 through 
50"; 


Related Attributes 


COMMENTS 
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NOENTRY 


Overview 


Use the NOENTRY attribute to prevent data entry during an 
INPUT or INPUT ARRAY statement. 


Syntax 


field-tag = table.column, NOENTRY; 


Explanation 


field-tag 


table. column 


NOENTRY 


Notes 


is the field tag used in the Screen section. 


is the name of a field (either related to a 
column or form-only). 


is the keyVv'ord indicating that no data entry 
may be made to this field during an INPUT or 
INPUT ARRAY statement. 


\. 


1. The NOENTRY attribute does not prevent you from enter- 
ing data into the field during a CONSTRUCT statement (to 
create a query-by-example). 
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Examples 


i 13 
items.stock_num; 
stock.stock_num, 
NOENTRY; 


When you are entering data intendefl for the stock table, the 
stock_num column is not available, since this SERIAL 
column gets its value from RDSQL during the INSERT state- 
ment. You can, however, use the same field to enter the stock 
number intended for the items table. 
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PICTURE 


Overview 


Use the PICTURE attribute to specify the character pattern 
for data entry to a CHAR type field. 


Syntax 


field-tag = table.column,PICTURE = "format-string"; 


Explanation 


field-tag 
is the field tag used in the Screen section. 


table.column 
is the name of a field (either related to a 
column or form-only). 


PICTURE 
is a required keyword. 


format-string 
is a string of characters that specify the 
desired character pattern. 


Notes 


1. 
format-string is a combination of three special symbols: 


Symbol 


A 
# 
X 


Meaning 


Any letter 
Any digit 
Any character 


Il"FORMIX-4GL treats any other character in the format- 
string as a literal. The cursor skips over such literal 
characters during data entry. 
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2. 
INFORMIX-4GL displays the literal characters in the display 
field and leaves blanks elsewhere. 
. 


3. If you attempt to enter a character not in conformity with 
the format-string, your terminal beeps and INFORMIX-4GL 
does not echo the character on the screen. 


4. The PICTURE attribute does not require the entry of the 
entire field; it only requires that what you enter conforms to 
format-string. 


5. The PICTURE must fill the entire width of the display 
field. 


Examples 


c10 = customer.phone, 
picture = "###-###-####x#####"; 


produces the following display field before data entry: 


x 


As another example, if you specify a field for part numbers 
like this 


f1 
= 
part_no, 
picture 
= 
"AA#####-AA(X)"; 


INFORMIX-4GL accepts any of the following inputs: 


LF49367-BB(*) 
TG38524-AS(3) 
YG67489-ZZ(D) 


The user does not enter the "-" nor the parentheses, but 
INFORMIX-4GL includes them in the string passed to the 
program variable. 
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REQUIRED 


Overview 


Use the REQUIRED attribute to force data entry in a 
particular field during an INPUT or INPUT ARRAY 
statement. 


Syntax 


field-tag = table. column, REQUIRED; 


Explanation 


field-tag 


table. column 


REQUIRED 


Notes 


is the field tag used in the Screen section. 


is the name of a field (either related to a 
column or form-only). 


is the keyword that instructs INFORMIX-4GL to 
insist upon data entry to the field-tag field. 


1. The REQUIRED keyword is effective only when 
table. column occurs in the list of screen fields of an 
INPUT or INPUT ARRAY statement. 


2. There is no default value for a REQUIRED field. If you 
assign both the REQUIRED attribute and the DEFAULT 
attribute to the same field, INFORMIX-4GL assumes that the 
DEFAULT value satisfies the REQUIRED attribute. 
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3. The REQUIRED attribute requires only that the user enter 
a printable character in the field. If the user subsequently 
erases the entry during the same input, INFORMIX-4GL con- 
siders the REQUIRED attribute satisfied. If you want to 
insist on a non-NULL entry, make the field form-only and 
NOT NULL. 


Examples 


020 = orders.po_num, 
REQUIRED; 


INFORMIX-4GL requires the entry of a purchase order value 
when you collect information for a new order. 
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REVERSE 


Overview 


Assign the REVERSE attribute to the fields you want 
INFORMIX-4GL to display in reverse video. 


Syntax 


field-tag = table. column, REVERSE; 


Explanation 


field-tag 


table.column 


REVERSE 


Notes 


is the field tag used in the Screen section.. 


is the name of a field (either related to a 
column or form-only). 


is the keyword that instructs INFORMIX-4GL 
to display the field-tag field in reverse 
video. 


1. On terminals that do not support reverse video, fields 
having the REVERSE attribute are enclosed in angle 
brackets < >. 
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UPSHIFT 


Overview 


Assign the UPSHIFT attribute to a CHAR field when you want 
INFORMIX·4GL to convert lowercase letters in data entry to 
uppercase letters, both on the screen and in the program 
variable corresponding to that field. 


Syntax 


field-tag = table. column, UPSHIFT; 


Explanation 


field-tag 


table. column 


UPSHIFT 


Notes 


is the field tag used in the Screen section. 


is the name of a field (either related to a 
column or form-only). 


is the keyword that instructs INFORMIX-4GL to 
convert CHAR input data to uppercase. 


1. Because uppercase and lowercase letters have different 
ASCII values, storing character strings in one or the other 
format can simplify sorting and querying a database. 
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Examples 


c8 
state, 
UPSHIFT, 
AUTONEXT, 
INCLUDE = 
("CA", 
"OR", 
"NV". 
'WA") , 
DEFAUL T = "CA" 
; 


Because of the UPSHIFT attribute, INFORMIX-4GL enters 
uppercase characters in the state field regardless of the case 
used to enter them. 


The AUTONEXT attribute tells INFORMIX-4GL to move 
automatically to the next field once you type the total number 
of characters allowed for the field (in this instance, two char- 
acters). The INCLUDE attribute restricts entry in this field to 
the characters CA, OR, NV, or WA only. The DEFAULT value 
for the field is CA. 


Related Attributes 


DOWNSHIFT 
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VALIDATE LIKE 


Overview 


Use the VALIDATE LIKE attribute to cause INFORMIX-4GL to 
validate the data entered into the field, using the attributes 
assigned to a database column in the syscolvaI table. 


Syntax 


field-tag = table. column, VALIDATE LIKE tbl.eal; 


Explanation 


field-tag 
is the field tag used in the Screen section. 


table. column 
is the name of a field (either related to a 
column or form-only). 


VALIDATE LIKE 
are required keyvmrds. 


tbl.col 
is the name of a column in the database. 


Notes 


1. This attribute is equivalent to listing all the attributes that 
you have assigned to tbl.col in the syscolvaI table. See the 
section "Default Screen Attributes," later in this chapter, 
for details on the syscolvaI table. 


2. You do not need the VALIDATE LIKE attribute if 
table.column is the same as tbl.eol. 
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Examples 


s13 = formonly.state. 
VALIDATE 
LIKE customer.state; 


Related Attributes 


DISPLAY LIKE 
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VERIFY 


Overview 


Use the VERIFY attribute when you want INFORMIX-4GL to 
require users to enter data twice for a particular field in order 
to reduce the probability of erroneous data entry. 


Syntax 


field-tag = table.column, VERIFY; 


Explanation 


field-tag 


table. column 


VERIFY 


Notes 


is the field tag used in the Screen section. 


is the name of a field (either related to a 
column or form-only). 


is the keyword that instructs INFORMIX-4GL to 
require duplicate data entry to the field-tag 
field. 


1. Since some data is critical, the VERIFY attribute supplies 
an additional step in data entry to ensure the integrity of 
the data in your database. After you enter a value into a 
VERIFY field and press RETURN, INFORMIX-4GL erases the 
field and requests that you re-enter the value. You must 
enter exactly the same data each time, character for 
character: 15000 is not exactly the same as 15000.00. 
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Examples 


For example, if you specify a field for salary information 
like this: 


510 
= 
quant ity, 
VERIFY; 


INFORMIX·4GL requires the entry of exactly the same data 
twice. 


Instructions Section 


The final section of the form specification file is the optional 
Instructions section. This section is used to 


• 
Specify alternate field delimiters 
• 
Define screen records and arrays 


The Instructions section begins with the INSTRUCTIONS 


ke~'\\'ord. It appears after the last attribute line of the 
Attributes section or the optional END keyword that concludes 
the Attributes section. 


INSTRUCTIONS 
Instructions 


[END] 


The END keyword is optional and may be omitted. 


DELIMITERS 


You may change the delimiters that INFORMIX·4GL uses to 
enclose fields when the form appears on the screen from 
brackets [ ] to any other printable character, including blank 
spaces. 
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Syntax 


DELIMITERS "ab" 


Explanation 


DELIMITERS is a required keyword. 


a 


b 


Notes 


is the opening delimiter. 


is the closing delimiter. 


1. The DELIMITERS instruction tells IXFORMIX-4GL what 
symbols to use as delimiters when it displays the fields on 
the screen. 


2. 
FORM4GL still requires brackets in the Screen section of a 
form specification file. 


3. Because the delimiter takes up a space, the closest that two 
fields can be on the screen is, ordinarily, two spaces. If you 
want to design your form to have only one space between 
fields, the following rules apply: 


• 
In the Screen section of your form specification file, use 
the vertical bar ( I ) to separate two fields in place of the 
standard pair of back-to-back brackets ][. 


SCREEN 


Fu I I 
Name-'-[ f011 
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If 0 12 


• 
In the Instructions section, define two new delimiters 
using identical symbols for both the beginning arid 
ending delimiters (for example, "I" or "/1" or "::"). 


DELIMITERS tI::tI 


When the fields fO 11 and fO 12 are displayed on the 
screen, they will appear as: 


Fu I I 
Name-: 


Screen Records 


You can collect groups of screen fields into screen records. You 
define the screen records in the Instructions section of the form 
specification file and refer to them in your INFORMIX-4GL 
program. 


Syntax 


SCREEN RECORD record-name 
(;table-name.* I 
table-name.column] THRU table-name.column2 I 
table-name.column:[. ...J) 


Explanation 


SCREEN RECORD 
are required keywords. 


record-name 


table-name 


is an RDSQL identifier. 


is the name of a table (or the keyword 
FORMONLY) that you have used in the 
Attributes section to define a field name. 
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columnl, 
column2, 
column 


THRU 


Notes 


are field names. 


is an optional keyword. The keyv-.'ord 
THROUGH is a synonym. 


1. 
table-name can be FORMONLY as well as a database 
table name. 


2. 
FORM4GL creates a default screen record for each table in 
the form specification file that is used to identify a field. 
The default record, which has the name of the table,con- 
tains components corresponding to only those columns in 
the table that are fields on the form. The order of the com- 
ponents is the order of the field names in the Attributes 
section. It is an error to define a screen record in the 
Instructions section with the name of a table in the form. 


3. The option of giving a range of field names with the THRU 
keyword assumes the order in which the fields are listed in 
the Attributes section. The THRU keyword is shorthand 
for listing all fields in the Attributes list between columnl 
and column2, inclusive of these fields as well. 


Examples 


The following example assigns a part of the fields correspond- 
ing to the columns of the customer table to a screen record. 
Such a screen record simplifies the INFORMIX-4GL statements 
that update customer address and telephone data. 


SCREEN RECORD address 
(customer.address1 
THRU customer.phone) 


All of the fields corresponding to columns from the customer 
table on the screen form constitute a default screen record with 
record-name customer. 
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Screen Arrays 


You may collect groups ofscreen fields into screen arrays. A 
screen array most often will be a physical array of identical 
rows of fields on the screen. Each column of the screen array 
consists of fields with the same tag. You define the screen 
arrays in the Instructions section of the form specification file 
and refer to them in your INFORMIX-4GL program. 


Syntax 


SCREEN RECORD record-name[n] 


(:table-name.* I 
table-name.column1 THRU table-name.column2 I 
table-name.column;L ...J) 


Explanation 


The syntax explanation is the same as for screen records (see 
the previous section) with the addition that n is a required 
integer parameter enclosed in brackets. 


Notes 


1. The integer n is the number of rows in a screen array. 
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Examples 


To illustrate, consider the following fragment from a form 
specification file: 


SCREEN 


I t em 
1 
[ P 
J[q 
j[u 
Item 2 
[p 
J[q 
j[u 
I t em 
3 
[ P 
j[q 
j[u 
I t em 
4 
[ P 
j[q 
j[u 
Item 
5 
[ P 
][q 
J[u 


][t 
][t 
][t 
][t 
][t 


TABLES orders, 
items, 
stock 


ATTRIBUTES 


p 
stock.stock_num; 
q 
items. qua n tit Y ; 
u 
stock.unit-price; 


t 
items.total-price; 


INSTRUCTIONS 
SCREEN 
RECORD 
s~_items[5J 
(stock.stock_num, 
items.quantity, 
stock.unit-price, 


items. tot a I-p ric e) 


The screen array has five rows and four columns. The rows are 
numbered from 1 to 5. 


Assuming there are no other columns of the items table in the 
form, there is a default screen record items containing two 
components: quantity and total-'price. 
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Default Screen Attributes 


As an alternative to entering attributes in the form 
specification file, you can enter them into two database tables. 
syscolval and syscolatt, using the upscol utility described in 
Appendix E. During the compilation of a form, FORM4GL 
searches these tables for data validation and screen attribute 
information for each column given as a field name. FOR:'\f4GL 
adds the attributes listed in these files to the attributes listed iL 
the form specification file. In case of conflict, the attributes 
explicitly mentioned in the form specification file have pre- 
cedence. INFORM:IX-4GL enforces the resulting set of attributes 
during the execution of the INPUT, INPUT ARRAY 
(syscolval) DISPLAY, and DISPLAY ARRAY (syscolatt) 
statements. 


The schema of the tables are as follows: 


syscolval 
syscolatt 


tabname 
colname 
attrname 
attrval 


char(l8) 
char(l8) 
char(lO) 
char(64) 


tabname 
colname 
seqno 
color 
inverse 
underline 
blink 
left 
def_format 
condition 


char( 18) 
char(l8) 
serial 
smallint 
charO) 
char(l) 
charO) 
char(l) 
char(64) 
char(64) 


tabname and colname are the names of the table and column 
to which the attributes apply. The permissible values for 
attrname and attrval in syscolval are shown in the 
following table: 


attrname 


INCLUDE 
PICTURE 
DEFAULT 
COMMENTS 
SHIFT 
VERIFY 
AUTONEXT 


attrval 


as in this chapter 
as in this chapter 
as in this chapter 
as in this chapter 
UP, DOWN, NO (the default) 
YES, NO (i,he default) 
YES. NO (the default) 
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The color column iIi syscolatt describes both color (for termi- 
nals that can display color) and intensities (for terminals with 
monochrome displays). The possible values for color are 
white, yellow, magenta, red, cyan, green, blue, and black. The 
following table shows the correspondence between the default 
color names and intensities. 


# 
color terminal 
monochrome terminal 


0 
White 
Normal 
1 
Yellow 
Bold 
2 
Magenta 
Bold 
3 
Red 
Boldt 
4 
Cyan 
Dim 
5 
Green 
Dim 
6 
Blue 
Dimt 
7 
Black 
Invisible 


The background for colors is BLACK in all cases. The t 
signifies that, if the keyword BOLD is indicated as the attri- 
bute, the field will be RED on a color terminal or, if the key- 
word DI~l is indicated as the attribute, the field will be BLUE 
on a color terminal. 


You may change the color names from the default list by asso- 
ciating different numbers with different color names in a file 
named colornames. If it exists in $INFORMIXDIR/incl (see 
Appendix C), FOR:M4GL examines colornames at compile time 
to obtain the correspondence between the numbers 0 through 7 
and the color names. 
(See Appendix N for the format of the 
colornames file.) 


The values for inverse, underline, and blink are Y (yes) and 
N (no). The default for each of these columns is N, that is, nor- 
mal display, no underline, and steady font. Which of these 
attributes can be displayed simultaneously with the color 
combinations or with each other is terminal-dependent. 
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The color, intensity, and other screen attributes interact with 
the termcap file on the user's computer for UNIX systems. 
Appendix N describes the changes that should be made to your 
termcap entry to enable these features for your terminal. On 
DOS systems, you can set your terminal characteristics at 
installation. 


Thedef_format column takes the same string that you would 
enter for the FORMAT attribute in a screen form. Do not use 
quotation markS, 


The condition column takes string values that are a restricted 
set of the "simple" \VHERE clauses of a SELECT statement, 
except that the WHERE keyword and the column name are 
omitted. "Simple" means that compound conditions formed by 
combining several Boolean expressions with AND or OR are 
not allowed. Examples of permitted entries for the condition 
column are as follows: 


<= 
100 


BEnNEEN 
101 
AND 
1000 
>= 
1001 
MATCHES "[A-MJ*" 
IN 
("CA". 
"OR". 
'WA") 
NOT LIKE 
'IO/oana I ys t%" 


INFORMIX-4GL assumes that the column identified by tabname 
and colname is the subject of all comparisons. 


The VALIDATE statement checks a program record or 
variable list against syscolval. 


The INITIALIZE statement looks up the default values listed 
in syscolval and assigns them to variables. 
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Following are the screen attributes allowed in ATTRIBUTE 
clauses of IXFORMIX-4GL statements: 


WHITE = NORMAL 
YELLOW = BOLD 
rvlAGENTA = BOLD 
RED = BOLD 
CYAN = DIM 
GREEN = DIM 
BLUE = DIM 
BLACK = INVISIBLE 


REVERSE 
BLINK 
UNDERLINE 


On color terminals, NORMAL is interpreted as WHITE; 
BOLD as RED; DIM as BLUE, and INVISIBLE as BLACK. 
If you have a colornames file, you may also use the color 
names listed there. 


You may override the default attributes in syscolatt by using 
either the ATTRIBUTE clause in a DISPLAY or DISPLAY 
ARRAY statement or assigning attributes in the form 
specification file. If you use the ATTRIBUTE clause in a 
DISPLAY or DISPLAY ARRAY statement, INFORMIX-4GL 
displays only the attributes mentioned in that clause. There is 
no carry-over of unmentioned display attributes from the com- 
piled form (except FORMAT). For example, if a column is 
desig-nated as RED and BLINK in syscolatt and you use the 
statement DISPLAY ... ATTRIBUTE BLUE, you get only the 
attribute BLUE. You do not get blinking BLUE. 


As stated earlier, the attributes in a form specification file and 
those in syscolval and syscolatt are combined, with the form 
specification file taking precedence in the event of conflict. 
The color (or intensity) attributes are available only through 
the ATTRIBUTE clause or through syscolatt, and conditional 
attributes are available only through syscolatt. You cannot 
use them in a form specification file. 


You can use the utility program upscol to create and enter 
attribute information into syscolval and syscolatt (see 
Appendix E for a description of upscol). 
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Creating and Compiling a Form 


You can create a form specification file and its customized 
screen form either through the INFOR:\lIX·4GL Programmer's 
Environment or directly from the operating system. Either 
alternative requires that you have already created the database 
and all the tables to which the form refers. The following two 
subsections describe these alternative procedures. 


Through the Programmer's Environment 


To create a customized screen form using the Programmer's 
Environment, you must follow these steps: 


1. Enter i4g1 in response to your operating system prompt. 


2. 
Select Form and then Generate from the menu. (Alter- 
nately, you can select the New option. I]\'FORMIX-4GL 
prompts you for a form name, prompts you for a system 
editor if you have not already selected one, and places you 
in that editor with an empty form specification file. You 
enter all form specification instructions. The Generate 
option is usually a more efficient way to create a custom 
form.) 


3. Enter the name of the database and the name you want to 
assign to the form (for example, myform). INFORMIX-4GL 
asks you for the names of the tables whose columns you 
want in your form. When you have selected all the tables 
you want to include, FORM4GL creates a default form 
specification file, as well as a compiled default form. 
INFORMIX-4GL returns you to the FORM Menu. 


4. The default form specification file formats the screen as a 
list of all the columns in the tables you entered in Step 3. 
It does not provide any special instructions to INFORMIX-4GL 
about how to display the data. Select the Modify option, 
and INFORMIX-4GL presents the MODIFY FORM Screen. 
Select the default form specification (given as myform 


earlier), and INFORMIX-4GL calls a system editor to display 
the file. Edit the default form specification file to produce 
your customized screen form and associated instructions. 
(You can specify an editor using the DBEDIT environment 
variable. This is fully explained in Appendix C.) When you 
write your file and quit the editor, you return to the 
MODIFY FORM Menu. 


5. Select Compile. If your form specification file compiles 
successfully, FORM4GL creates a form file with the extension 
.frm (for example, myform.frm). Go on to Step 7. If 
your form specification file does not compile successfully, 
go on to Step 6. 


6. Select the Correct option from the COMPILE FORM 
Menu. INFORMIX-4GL again calls your editor to display the 
form specification file, with the compilation errors marked. 
When correcting your errors, you need not delete the error 
messages. INFORMIX-4GL does that for you. Save the file 
and go to Step 5. 


7. Save your form specification file with the Save-and-exit 
option. 


Through the Operating System 


To create a customized screen form directly from the operating 
system, follow these steps: 


1. Create a default form specification file by entering the 
command 


form4g1 -d 


at the operating system prompt. FORM4GL asks for the 
name of your form specification file, the name of your data· 
base, and the name of a table whose columns you want in 
your form. It continues to ask for another table name until 
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you enter a RETURN for the name of a table. FORM4GL then 
creates a default form specification file and appends the 
extension .per to its name. It also creates a compiled 
default form with the extension .frm. 


2. Use a system editor to modify the default form specification 
file to meet your specifications. If, as an alternative, you 
create a form specification file from scratch and skip Step 1, . 
be sure to give the filename the extension .per. 


3. Enter the command 


form4g1 myform 


where myform is the name of your form specification 
file (without the .per extension). If the compilation is 
successful, FORM4GL creates a compiled form file called 


. myform.frm and you are finished creating your customized 
screen form, If not, FORM4GL creates a file named 
myform.err, and you need to go on to Step 4. 


4. 
Review the file myform.err to discover the compilation 
errors. Make corrections in the file myform.per. Go to 
Step 3. 


-3 
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Using PERFORl\I Forms in INFORl\iIX-4GL 


If you have designed forms to use with the PERFORM screen 
transaction program of I::'\FOR'\HX-SQL, you need to know how 
those forms behave when used with INFORMIX-4GL. The follow- 
ing is a list of the features regarding forms that differ between 
PERFORM and I::'\FORMIX-4GL: 


• 
Only the DELIMITERS statement in the Instructions 
section of a PERFORM form specification is applicable in 
INFORMIX-4GL. All other statements are ignored. To 
achie\'e the same effects, you must code them into your 
I::'\FORMIX-4GL program (see the BEFORE and AFTER 
clauses of the INPUT statement). 


• 
I\1ultiple-screen forms \vill not work with I::'\FOR:\HX-4GL and 
will produce undesirable overlays. You can achieH similar 
efi'ects in I::'\FOR:\HX-4GL but you must code them explicitly. 


• 
There is no concept of "current table" in I::'\FOR:\IIX-4GL. A 
single INPUT or INPUT ARRAY statement allows you to 
enter data into fields that correspond to columns in 
difi'erent tables. 


• 
,Joins defined in the PERFORM form specification are ignored 
in I::'\FOR:\HX-4GL You may associate two field names to the 
same field tag using the same notation as in a PERFOR!\I join, 
but no join is effected. 
On the other hand. you can create 
more complex joins and look-ups in I::'\FORMIX-4GL using the 
full power of RDSQL. 


• 
The PERFOR!\I attributes LOOKUP, NOUPDATE, 
QUERYCLEAR. RIGHT. and ZEROFILL are inoperative 
in INFOR!\HX-4GL 


• 
The default attributes listed in syscolval and syscolatt 
do not apply to your PERFOR!\I forms unless you recompile 
them. 
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Chapter 4 


Report Writing 
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Chapter Overview 


IJ"FORMIX-4GL provides all the tools of a general-purpose 
relational report writer. .Reports in INFORMIX-4GL have the 
following features: 


• 
You have full control over page layout for your report. This 
includes first-page headers that differ from headers on sub- 
sequent pages, page trailers, columnar data presentation, 
special formatting before and after groups of sorted data, 
and conditional formatting that depends upon the data. 


• 
. INFORMIX-4GL provides aggregate functions that permit you 
to compute percentages, sums, averages, maximums and 
mInImUms. 


• 
You can use all the built-in functions of INFORMIX-4GL, 
including the USING function (see Chapter 1). 


• 
You can create the report either from the rows returned by 
a cursor or from report records assembled from any other 
source. such as the output of several different SELECT 
statements. 


• 
You can manipulate the data returned by the cursor on a 
row-by-row basis either before or after the row is formatted 
by the report. 


• 
You can update the database or perform any other sequence 
of Il"FORMIX-4GL statements in the middle of writing a 
report if the intermediate values calculated by the report 
meet your criteria. For example. you could even write an 
alert message containing a second report. 


You must define a routine of type REPORT outside the 
MAIN program. This chapter describes the rules for writing 
REPORT routines. 
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Calling a REPORT Routine 


You call a REPORT routine through three statements that 
occur before, during, and after a program loop that you define: 


START REPORT report-name 
[TO :PRINTER I PIPE program I filename:] 


OlTTPUT TO REPORT report-name(variable-list) 


FINISH REPORT report-name 


The basic loop structure (whether a FOR, FOREACH, or 
WHILE loop) is illustrated below: 


START REPORT 
report1 
begi,n 
loop 
# of whatever 
kind 


OUTPUT 
TO REPORT 
report l(customer .') 


end 
loop 
FINISH REPORT 
report1 


The START REPORT statement initializes the report and, 
optionally, determines the output file or de'-lice. The OUTPUT 
TO REPORT statement tells INFORMIX-4GL to process the next 
row of the report. The FINISH REPORT statement handles 
the end of report summaries. You can find the full syntax for 
these three statements in Chapter 7. 
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Structure of a REPORT Routine 


A report routine is composed of sections that are made up of 
control blocks and/or statements. Each statement can contain 
clauses made up of keywords and expressions. You must 
observe the order of the sections shown in the following syntax 
diagram when you write an INFORMIX-4GL report routine. 


Syntax 


REPORT report-name (argument-list) 


[DEFINE section] 
[OUTPUT section] 
[ORDER BY section] 
FORMAT section 
END REPORT 


REPORT 
is a required keyword. 


report-name 
is an INFORMIX-4GL identifier. 


argument-list 
is a list of variables or record identifiers, 
separated by commas. Record identifiers 
must not have a .* extension. 


END REPORT are required keywords. 


Notes 


1. The DEFINE, OUTPUT, ORDER BY, and FORMAT 
sections are described in later sections of this chapter. 


2. A minimal report consists only of the FORMAT section. 
You may, optionally, include other sections as needed. 
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Examples 


Several REPORT routines are included with the demonstration 
application listed in Appendix A. They illustrate a wide 
variety of the commands available for writing reports with 
INFORMIX-4GL and provide most of the example text in the 
pages that follow. 


DEFINE Section 


An I]\"FORMIX-4GL REPORT routine requires a DEFINE section 
when you pass arguments to the report or use local variables in 
the report. You must have an argument-list under the 
following conditions: 


• 
When there is an ORDER BY section in your report. In 
this case, you must pass all the values for each row of the 
report. 


• 
When you use the GROUP PERCENT aggregate function 
anywhere in your report or use any aggregate function over 
all the rows of the report at any place except in the ON 
LAST ROW control block. In short, if you print an aggre- 
gate dependent on all rows of the report in the middle of . 
the report, you must pass the rows of the report through the 
argument-list. 


• 
When you use the FORMAT EVERY ROW control block. 
In this case, you must pass all the values for each row of the 
report. 


• 
When you use the AFTER GROUP OF control block. In 
this case, you must pass at least the parameters named in 
the AFTER GROUP OF statement. 


The DEFINE section obeys the same rules as given in 
Chapter 7 for the DEFINE statement, except that report 
parameters may not be of type ARRAY nor records with 
ARRAY members. 
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OUTPUT Section 


An INFORMIX-4GL REPORT routine can, optionally, contain an 
OUTPUT section. The OUTPUT section controls the width of 
the margins and the length of the page. The OUTPUT section 
also allows you to direct the output from the INFORMIX-4GL 
report to a file -or the system printer. On UNIX systems, you 
can also direct output to a pipe. 


The OUTPUT section consists of the OUTPUT keyvwrd, 
followed by one or more statements. The structure of an 
OUTPUT section is shown below. 


You cannot use more than one of the REPORT TO options 
in a REPORT routine. When you do not use one of the 
REPORT TO options, INFORMIX-4GL sends the report to 
your screen. 


OUTPUT 
[REPORT TO statement] 
[LEFT MARGIN statement] 
[RIGHT MARGIN statement] 
[TOP MARGIN statement] 
[BOTTOM MARGIN statement] 
[PAGE LENGTH statement] 
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REPORT TO 


Overview 


This statement directs the output of the INFORMIX-4GL report 
to a file, to an operating system pipe (UNIX systems only), or 
to the system printer. 


S)'ntax 


REPORT TO i"jilename" I PIPE program I PRINTER: 


Explanation 


REPORT TO 
are required keywords. 


filename 
is a quoted string containing the name of a 
system file that will receive the report. 


PIPE 
is an optional keyword. 


program 
is a variable of type CHAR or a quoted string 
containing the name of a UNIX program that 
is to receive the output from the INFORMIX·4GL 
report. The program name, and any associated 
arguments, must be within quotation marks. 


PRINTER 
is an optional keyword. 


Notes 


;, 
1. If the START REPORT statement has a TO clause 
directing the output of the report to a file, pipe, or printer, 
INFORMIX-4GL ignores the REPORT TO statement of the 
OUTPUT section. 
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2. If filename is a variable, you must pass it as an argument to 
the REPORT routine. 


3. The REPORT TO PRINTER statement causes 
lNFORMIX-4GL to send the report to the program named by 
the DBPRINT environment variable. If you do not set this 
variable, INFORMIX-4GL sends the report to the lp program 
(on UNIX systems) or the lptl printer (on DOS systems), 


4. If you want to send the report to a printer other than tht 


system printer, you can use the REPORT TO filename 
statement to send the output to a file and then send the file 
to the printer of your choice. On UNIX systems, you can 
also use the REPORT TO PIPE statement to direct the 
output to a program that sends the output to the correct 
printer. 


Examples 


The following OUTPUT section directs the report output to 
the label.out system file. 


OUTPUT 
REPORT 
TO "label .out" 
LEFT MARGIN 0 
TOP MARGIN 0 
BOTTOtv1 MARGIN 0 
PAGE 
LENGTH 6 


The following OUTPUT section directs the output from the 
INFORMIX-4GL report to the more utility. 


OUTPUT 
REPORT 
TO PIPE "more" 
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LEFT MARGIN 


Overview 


This statement sets a left margin for a report. 


Syntax 


LEFT MARGIN integer 


Explanation 


LEFT MARGIN 


integer 


Notes 


are required keywords. 


is an integer that specifies the width of 
the left margin, in spaces. 


1. The default left margin is five spaces. 


2. All columnar displacement indicated by the COLUMN 
function starts at the margin set by LEFT MARGIN. 
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Examples 


The following LEFT MARGIN statement instructs 
INFORMiX-4GL to print the left side of the report as ~r to the 
left as possible. 


OUTPUT 
REPORT 
TO "Iabel.out" 
LEFT MARGIN 0 
TOP MARGIN 0 
BOTTOM MARGIN 0 
PAGE 
LENGTH 6 
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RIGHT MARGIN 


Overview 


This statement sets a right margin for a report. 


Syntax 


RIGHT MARGIl\ integer 


Explanation 


RIGHT I\·1ARGI:\ 


in teger 


Notes 


are required keyword~. 


is an integer that specifies the width of 
the text on the page, in characters. 


1. The RIGHT MARGIN determines the right margin by 
specifying the width of the page. in characters. It is nOl 
dependent on the LEFT MARGIN. but always starts its 
count from the left edge of the page. 


2. The RIGHT MARGIN is effective only when the FORMAT 
section contains an EVERY ROW statement. 


3. The default RIGHT MARGIN is 132. 


4. 
II\FORMIX-4GL attempts to produce an EVERY RO\V report 
by listing the variable names across the top of the page and 
presenting the data in columns beneath these headings. If 
there is not sufficient room between the LEFT MARGIN 
and the RIGHT MARGIN to do this. II\FORMIX-4GL pro- 
duces a report that lists the variable names and the data 
of each row in two columns. 


4-14 Structure of a REPORT Routine 


Examples 


The following example demonstrates the use of the RIGHT 
1\1ARGI::-\ statement. I::\'FOR\1IX-4GL sets the right margin for 
the report at 70 characters. 


REPORT simple(customer) 
DEFINE customer 
LIKE customer. 
OUTPUT 
RIGHT MARGIN 
70 


FORMAT 
EVERY 
RCV": 


END REPORT 
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TOP MARGIN 


Overview 


This statement sets a top margin for a report. 


Syntax 


TOP MARGIN integer 


Explanation 


TOP l'vlARGIN are required ke:ywords. 


integer 


Notes 


is an integer that specifies the number of blank 
lines that INFORMIX-4GL leaves at the top of 
each page. 


1. The default top margin is three lines. 


2. The top margin appears above any page header you specify. 


4-16 Structure of a REPORT Routine 


Examples 


The following TOP MARGIN statement instructs 
INFORMIX-4GL to begin printing at the top of each page. 


OUTPUT 
REPORT 
TO "label .Qut" 
LEFT MARGIN 0 
TOP MARGIN 0 
BOTTOM MARG IN 0 
PAGE 
LENGTH 6 
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BOTTOM MARGIN 


Overview 


This statement sets a bottom margin for a report. 


Syntax 


BOTTOM MARGIN integer 


Explanation 


BOTTOM MARGIN 
are required keywords. 


integer 
is an integer that specifies the number 
of blank lines that Il'FORMIX-4GL is to 
leave at the bottom of each page. 


Notes 


1. The default bottom margin is three lines. 


2. The bottom margin appears below any page trailer you 
specify. 
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Examples 


The following BOTTOM MARGIN statement instructs 
IXFORMIX-4GL to continue printing to the bottom of each page. 


OUTPUT 
REPORT 
TO "label .out" 
LEFT MARG IN 0 
TOP MARGIN 0 
BOTTOM MARGIN 0 
PAGE 
LENGTH 6 


PAGE LENGTH 


Overview 


This statement sets the number of lines on each page of a 
report. 


Syntax 


PAGE LENGTH integer 


Explanation 


PAGE LENGTH 


integer 


Notes 


are required keywords. 


is an integer that specifies the length of 
the page, in lines. 


1. The default page length is sixty-six lines. 


2. The PAGE LENGTH includes the TOP MARGIN and 
BOTTOM MARGIN. 


Examples 


The following example demonstrates the use of the PAGE 
LENGTH statement. INFORMIX-4GL prints each page with 22 
lines. On a standard 24-line video screen, a page length of 22 
lines is the longest you can use with the PAUSE statement 
without causing undesirable scrolling. 


OUTPUT 
PAGE 
LENGTH 22 
TOP MARGIN 0 
BOTTOM MARGIN 0 


4-20 Structure of a REPORT Routine 


ORDER BY Section 


The optional ORDER BY section specifies the variables on 
. which you want the rows to be sorted and the order in which 


INFORMIX-4GL will process group control blocks in the 
FORMAT section. You should have an ORDER BY section if 
you have used group control blocks in your report and 


• 
you have not sorted the input rows, or 


• 
you have already sorted the input rows and you want to 
specify the exact order in which the group control blocks are 
processed. 
(Without the ORDER BY section INFORMIX·4GL 


chooses the order in which to process the group control 
blocks.) In this case, use the EXTERNAL keyword so that 
the rows will not be sorted again. 


ORDER [EXTERl\'AL] BY sort-list 


Explanation 


ORDER BY 
are required keywords. 


EXTERNAL 
is an optional keyword. 


sort-list 
is a list of one or more variables from the list 
of arguments to the REPORT routine. 


Notes 


1. The ORDER BY section specifies two things. First, it 
specifies the order in which INFOR!\IIX-4GL orders the input 
rows. If sort-list contains a, b, and c in that order, then 
INFORMIX-4GL orders the input rows first by a. Within that 
ordering, INFORMIX-4GL orders the rows next by b. Finally, 
INFORMIX-4GL orders the resulting rows by c. 
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Second, the ORDER BY section specifies the order in which 


I~FORMIX·4GL will process group control blocks. (See the 
section "Control Blocks" for more information.) 


2. The EXTERNAL keyv.'ord in the ORDER BY section 
specifies that the input rows are already sorted. 
INFORMIX-4GL does not resort the rows in this case and 
prints the report with one pass through the input rows. 


3. If there is an ORDER BY section without the EXTERNAL 
keyword, INFORMIX-4GL makes two passes through the input 
data. During the first pass, it sorts the data and stores it in 
a temporary file. During the second pass, it prints the 
report. Since sorting within a SELECT statement makes 
use of indexes while sorting within the REPORT routine 
does not, you may find that external sorting increases the 
performance of your program. You may also want to sort 
your data outside of the REPORT routine if your program 
experiences memory limitations. 


If the input rows for your report come from the rows 
returned by only one cursor, you should use the ORDER BY 
clause in the SELECT statement associated with the cursor, 
and use the EXTERNAL keyword in the ORDER BY 
section of your report. 


4. If you have just one variable named in group control blocks 
and the input rows are already sorted, then you do not need 
an ORDER BY section. 


FORMAT Section 


An I~FORMIX-4GL REPORT routine must contain a FORMAT 
section. The FORMAT section determines what the report will 
look like. It works with the data that is passed to the routine 
through the argument list or with data that you put in global 
variables for each row of the report. 
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The FORMAT section begins with the FORMAT keyword and 
ends at the end of the REPORT routine, that is, with the END 
REPORT keywords. 


There are two major types of FORMAT sections. The simplest 
FORMAT section contains only an EVERY ROW statement 
between the FORMAT and END REPORT keywords. If you 
use an EVERY ROW statement, you cannot use any other 
statements or control blocks in the FORMAT section. The 
following example shows the structure of this type of FORMAT 
section. 


FORMAT 
EVERY ROW 
END REPORT 


More complex FORMAT sections can contain control blocks 
such as ON EVERY ROWand BEFORE GROUP OF. Each of 
these control blocks must contain at least one FORMAT state- 
ment such as PRINT or SKIP n LINES and may contain other 
INFORMIX-4GL statements. 


If you do not use an EVERY ROW statement, you can combine 
control blocks as required. You can place control blocks in any 
order within the FORMAT section. The following shows the 
structure of this type of FORMAT section. 


FORMAT 
[PAGE HEADER control block] 
[PAGE TRAILER control block] 
[FIRST PAGE HEADER control block] 
[ON EVERY ROW control block] 
[ON LAST ROW control block] 
[BEFORE GROUP OF control block 
...] 
[AFTER GROUP OF control block 
...] 
END REPORT 
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EVERY ROW 


Overview 


The EVERY RO\V statement causes INFOHMIX·4GL to output 
every row that you pass to the report. It uses a default format. 


Syntax 


EVERY ROW 


Explanation 


EVERY ROW 
are required keywords. 


Notes 


L The report consists of only the data that you pass to the 
routine through its arguments. 


2. This statement is useful when you want to run a quick 
report using a default format. 


3. The EVERY ROW statement stands by itself-you 
cannot modify it with any of the statements listed in the 
"Statements" section of this chapter. 


4. When you use the EVERY ROW statement, you cannot use 
any control blocks in the FORMAT section. 


5. A report generated by an EVERY ROW statement uses the 
variable names that you pass as arguments to the routine at 
run time as column headings. 
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6. If the variables you passed as arguments fit on a line, 


Il"FORMIX·4GL will produce a report with variable names 
across the top of each page; otherwise, it will produce a 
report with the variable names down the left side 
of the page. 


7. You can use the RIGHT MARGIN statement in the 
OUTPUT section to control the width of a report that uses 
the EVERY ROW statement. 


8. Use the ON EVERY RO\V control block if you want to 
display every row in a format other than the default format. 
(See the discussion of ON EVERY RO\\' in the "Control 
Blocks" section later in this chapter.) 


Examples 


The following example shows a minimal INFOR!\fIX-4GL 
REPORT routine using the EVERY ROW statement. 


REPORT minimal (customer) 
DEFINE customer 
RECORD LIKE customer.· 
FORMAT 
EVERY RON 
END REPORT 
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The following display shows a portion of the output from the 
preceding specification. 


customer.customer 
num 
c us tome r . f name 
c us tome r . I name 
c us tome r . c omp any 
c us tome r . add res s 1 
customer.address2 
c us tome r . cit y 
c us tome r . s tat e 
c us tome r . zip cod e 
customer.phone 


c us tome r . c us tome r_n um 
c us tome r . f name 
c us tome r . I name 
customer.company 
customer.address1 
c~stomer.address2 
c us tome r . cit y 
customer.state 
customer.zipcode 
c us tome r . ph 0 ne 


c us tome r . c us tome r_ num 
c us tome r . f name 
c us tome r . I name 


101 
Ludwig 
Pau I i 
All Sports Suppl ies 
213 
E r s t w i I d Co u r t 


Sunnyvale 
CA 
94086 
408-789-8075 


102 
Carole 
Sadler 
Sports Spot 
785 Geary St 


San Francisco 
CA 
94117 
415-822-1289 


103 
Ph iii P 
Cu r r i e 


Below is another example of a brief report specification that 
uses the EVERY ROW statement. 


REPORT simple(order-yum, 
customer_num, 
order_date) 
DEFINE order_num LIKE orders.order_num, 
customer_num LIKE orders.customer_num, 
order_date 
LIKE orders.order_date 
FORMAT 
EVERY RON 
END REPORT 
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The following display shows the output from the preceding 
REPORT routine. 


order 
num customer 
num order date 


1001 
104 
01/20/1986 
1002 
101 
·06/01/1986 
1003 
104 
10/12/1986 
1004 
106 
04/ 12/ 1986 
1005 
116 
12/04/1986 
1006 
1 12 
09/19/1986 
1007 
1 17 
03/25/1986 
1008 
110 
11/17/1986 
1009 
1 1 1 
02/14/1986 
1010 
115 
OS/29/1986 
101 1 
104 
03/23/1986 
1012 
117 
06/05/1986 
1013 
104 
09/01/1986 
1014 
106 
05/01/1986 
1015 
110 
07/10/1986 
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Control Blocks 


Control blocks provide the structure for a custom report. Each 
control block is optional but, if you do not use the EVERY 
ROW statement, you must include at least one control block in 
a REPORT routine. 


Each control block must include at least one statement (see the 
"Statements" section later in this chapter). 


When you use the BEFORE GROUP OF, AFTER GROUP OF, 
and ON EVERY ROW control blocks in a single REPORT 
routine, INFORl\IIX-4GL processes all BEFORE GROUP OF 
blocks before the ON EVERY ROW block and the ON EVERY 
ROW block before all AFTER GROUP OF blocks. The order 
in which I]\"FORMIX-4GL processes the BEFORE GROUP OF 
control blocks and AFTER GROUP OF control blocks depends 
upon the hierarchy of variables listed in the ORDER BY sec- 
tion or, in the absence of an ORDER BY section, implied by 
the order of first mention of variables in either BEFORE or 
AFTER GROUP OF control blocks. Assume that the ORDER 
BY section orders by variables a, b, and c. Then the following 
display indicates the order by which INFORMIX-4GL processes 
control blocks: 


BEFORE GROUP OF a 
BEFORE GROUP OF b 
BEFORE GROUP OF c 
ON EVERY ROW 
AFTER GROUP OF c 
AFTER GROUP OF b 
AFTER GROUP OF a 


Figure 4-1. Order of Group Processing 
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AFTER GROUP OF 


Overview 


The AFTER GROUP OF control block specifies the action 
Il"FORMIX-4GL takes after it processes a group of rows. 
Grouping is determined by the ordering you did earlier. 


Syntax 


AFTER GROUP OF variable-name 
statement 


Explanation 


AFTER GROUP OF are required keywords. 


variable-name 


statement 


Notes 


is the name of one of the variables passed 
as an argument. 


is a FORMAT or Il"FORMIX-4GL 
statement. 


1. You must pass at least the value of variable-name through 
the arguments of the REPORT routine. 


2. A group of rows is all rows that contain the same value for a 
given variable. INFORMIX-4GL automatically groups rows 
when you use an ORDER BY section of a REPORT routine 
or the ORDER BY clause in a SELECT statement-that is, 
groups come together when you order a list. 
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When you specify more than one column in the ORDER BY 
section or clause, INFORMIX-4GL orders the rows first by the 
first variable you specify (most significant), second by the 
second variable you specify, and so on, until the last 
variable you specify (least significant) is ordered. 


INFORMIX-4GL processes the statements in an AFTER 
GROUP OF control block each time the specified column 
changes value, each time a more significant column changes 
value, and at the end of a report (refer to Figure 4-1 at the 
beginning of the "Control Blocks" section). 


3. You can have one AFTER GROUP OF control block for 
each variable on which you have ordered the data. 


4. If you have an ORDER BY section and you have more than 
one AFTER GROUP OF control block, their order within 
the FORMAT section is not significant. 


5. When INFORMIX-4GL finishes generating a report, it executes 
all of the statements in the AFTER GROUP OF control 
blocks before it executes those in the ON LAST ROW 
control block. 


6. Group aggregates can be used only in AFTER GROUP OF 
control blocks. You cannot use group aggregates in any 
other control blocks. 


7. When INFORMIX-4GL processes the statements in an AFTER 
GROUP OF control block, the variables of the report still 
have the values from the last row of the group. From this 
perspective, the AFTER GROUP OF control block could be 
called the "on last row of group" control block. 
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Examples 


AFTER GROUP OF 
r.order 
num 
PRINT" ",r.order date,7 SPACES,r,order 
num USING "###&" , 
8 
SPACES, r ship date, " 
GROUP SUM(" 
lolal-price) 
USING "SSSS,SSS,SSS,&&" 


AFTER GROUP OF 
r customer 
num 
PR INT 
42 SPACES,"···· .-:- 
" 


PRINT 
42 
SPACES,GROUP SUM(r.lolal-price) 
USING "SSSS.SSS,SSS.&&" 


4-31 


BEFORE GROUP OF 


Overview 


The BEFORE GROUP OF control block specifies what action 
INFORMIX-4GL takes before it processes a group of rows. 
Grouping is determined by the ordering you did earlier. 


Syntax 


BEFORE GROUP OF variable-name 
statement 


Explanation 


BEFORE GROUP OF 


variable-name 


statement 


Notes 


are required keywords. 


is the name of one of the variables 
passed as an argument. 


is a FORMAT or INFORl\HX-4GL 
statement. 


1. You must pass at least the value of variable-name through 
the arguments of the REPORT routine. 


2. A group of rows is all rows that contain the same value for a 
given variable. INFORMIX·4GL automatically groups rows 
when you use an ORDER BY section of a REPORT routine 
or the ORDER clause of a SELECT statement-that is, 
groups come together when you order a list. 
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When you specify more than one variable in an ORDER BY 
section or clause, INFORMIX-4GL orders the rows first by the 
first variable you specify (most significant), second by the 
second variable you specify, and so on, until the last 
variable you specify (least significant) is ordered. 


INFORMIX-4GL processes the statements in a BEFORE 
GROUP OF control block at the start of a report, each time 
the specified variable changes value, and each time a more 
significant variable changes value (refer to Figure 4-1 at the 
beginning of the "Control Blocks" section). 


3. You can have one BEFORE GROUP OF control block for 
each variable that you order. 


4. If you have an ORDER BY section and you have more than 
one BEFORE GROUP OF control block, their order within 
the FORMAT section is not significant. 


5. When INFORMIX-4GL starts to generate a report, it executes 
all the statements in the BEFORE GROUP OF control 
blocks before it executes those in the ON EVERY ROW 
control block. 


6. You can use a SKIP TO TOP OF PAGE statement in a 
BEFORE GROUP OF control block to cause each group to 
start at the top of a page. 


7. When INFORMIX-4GL processes the statements in a BEFORE 
GROUP OF control block, the report variables have the 
values from the first row of the new group. From this per- 
spective, the BEFORE GROUP OF control block could be 
called the "on first row of group" control block. 
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Examples 


BEFORE GROUP OF 
r.customer_num 
SKIP TO TOP OF PAGE 
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FIRST PAGE HEADER 


Overview 


The FIRST PAGE HEADER control block specifies what 
information appears at the top of the first page of the report. 


Syntax 


FIRST PAGE HEADER 
statement 


Explanation 


FIRST PAGE HEADER 
are required keywords. 


statement 
is an INFORMIX·4GL or FORMAT 
statement. 


Notes 


1. The TOP MARGIN (set in the OUTPUT section) affects 
how close to the top of the page INFORMIX·4GL displays the 
page header. 


2. A FIRST PAGE HEADER control block overrides a PAGE 
HEADER control block on the first page of a report. 


3. You cannot use the SKIP TO TOP OF PAGE statement in 
a FIRST PAGE HEADER control block. 


4. If you use an IF THEN ELSE statement in a FIRST PAGE 
HEADER control block, the number of lines displayed by 
the PRINT statements following the THEN keyword must 
be equal to the number of lines displayed by the PRINT 
statements following the ELSE keyword. 
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5. You cannot use the PRINT filename statement to read and 
display text from a file in a FIRST PAGE HEADER control 
block. 


6. You can use a FIRST PAGE HEADER control block to 
produce a title page, as well as column headings. 


Examples 


This example is from a report that produces multiple labels 
across the page. 


FIRST 
PAGE 
HEADER 
:Nothing 
is 
displayed 
in 
this 
control 
block. 
It 
just 
init ial izes 
var iables 
that 
are 
used 
in 
the 
ON 
EVERY 
ROW 
control 
block.: 


ilnitialize 
label 
counter.! 
LET 
i = 
1 


:Determine 
label 
width 
(allow 
eight 
spaces 
total 
between 
labels).: 
LET 
I_size 
= 
72/cQunt1 


:Divide 
the 
eight 
spaces 
between 
the 
number 
of 
labels 
across 
the 
page.: 
LET white = 8/count1 


This FIRST PAGE HEADER does not display any infor- 
mation. Because INFORMIX-4GL executes the FIRST PAGE 
HEADER control block before it generates any output, you can 
use this control block to initialize variables that you use in the 
FORMAT section. 
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ON EVERY ROW 


Overview 


The ON EVERY ROW control block specifies what action 


Il"FORMIX~4GLis to take for every row of data that you pass to 
the routine. 


Syntax 


Or\' EVERY RO\\" 
statement 


Explanation 


ON EVERY ROW 
are required keywords. 


statement 
is an Il"FORMIX·4GL or FORMAT 
statement. 


Notes 


1. 
INFOR:\flX-4GL processes the statements in an ON EVERY 
RO\V control block as each new row is formatted. 


If a BEFORE GROUP OF control block is triggered by a 
change in column value, all appropriate BEFORE GROUP 
OF control blocks will be executed (in the order of their 
significance) before the ON EVERY ROW control block is 
executed. 


If an AFTER GROUP OF control block is triggered by a 
change in column value, all appropriate AFTER GROUP 
OF control blocks will be executed (in the reverse order of 
their significance) after the ON EVERY ROW control block 
is executed. 
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Examples 


The following example is from a report that lists all the 
customers, their addresses, and their telephone numbers across 
the page. 


ON EVERY RON 


PR INT c us tome r num US ING "####", 
COLUMN 12, fname CLIPPED, 
1 SPACE, 
Iname CLIPPED, 
COLUMN 35, city CLIPPED, 
", 
" 
, 
s tat e , 
COL UMN 57, 
zip cod e , 
COLUMN 65, 
phone 


The following example is from a mailing label report. 


ON 
EVERY 
RON 


IF 
(city 
IS 
NOT 
NULL) 
AND 
(stele 
IS 
NOT NULL) 
THEN 
PR I NT 
f name 
CL I PPED, 
1 SPACE, 
I neme 
PRINT 
company 
PRINT address1 
IF 
(address2 
IS 
NOT NULL) 
THEN 
PRINT address2 
PRINT city CLIPPPED 
'I, 
" 
• 
stete. 
2 SPACES, 
zipcode 
SKIP 
TO 
TOP 
OF 
PAGE 
END 
IF 
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ON LAST ROW 


Overview 


The ON LAST ROW control block specifies what action 
INFORMIX-4GL is to take after it processes the last row passed 
to the REPORT routine. 


Syntax 


ON LAST ROW 


statement 


Explanation 


ON LAST ROW 


statement 


Notes 


are required keywords. 


is an INFORMIX-4GL or FORMAT 
statement. 


1. 
INFORMIX-4GL executes the statements in the ON LAST 
ROW control block after it executes those in the ON 
EVERY ROWand AFTER GROUP OF control blocks. 


2. You can use the ON LAST ROW control block to display 


report totals. 


3. When INFORMIX-4GL processes the statements in an ON 
LAST ROW control block, the columns that the report is 
processing still have the values from the final row that the 
report processed. 
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Examples 


ON LAST RON 
SKIP 
1 LINE 
PRINT COLUMN 
12. 
"TOTAL 
NUMBER OF CUSTOMERS:", 
COLUMN 57, 
COUNT(·) 
USING "#r' 
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PAGE HEADER 


Overview 


The PAGE HEADER control block specifies what information 
appears at the top of each page of the report. 


Syntax 


PAGE HEADER 
statement 


Explanation 


PAGE HEADER 


statement 


Notes 


are required keywords. 


is an INFORMIX-4GL or FORMAT 
statement. 


1. The TOP MARGIN (in the OUTPUT section) affects how 
close to the top of the page INFORMIX-4GL displays the page 
header. 


2. A FIRST PAGE HEADER control block overrides a PAGE 
HEADER control block on the first page of a report. 


3. You cannot use the SKIP TO TOP OF PAGE statement in 
a PAGE HEADER control block. 


4. The number of lines produced by the PAGE HEADER 
control block may not change from page to page and must 
be unambiguously expressed. The following rules are special 
cases of this more general principle: 
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• 
You cannot have a SKIP integerLINES inside a loop in 
the PAGE HEADER control block. 


• 
You cannot use a NEED statement in the PAGE 
HEADER control· block. 


• 
If you use an IF THEN ELSE statement in a PAGE 
HEADER control block, the number of lines displayed 
by the PRINT statements following the THEN keyword 
must be equal to the number of lines displayed by the 
PRINT statements following the ELSE keyword. 


• 
If you use a CASE, FOR, or WHILE statement that 
contains a PRINT statement in a PAGE HEADER con- 
trol block, you must terminate the print statement with 
a semicolon. The semicolon will suppress RETURNS 
in the loop, keeping the number of lines in the header 
constant from page to page. 


• 
You cannot use a PRINT filename statement to read and 
display text from a file in a PAGE HEADER control 
block. 


5. You can use a PAGE HEADER control block to display 
column headings in a report. 


6. You can use the PAGENO expression in a PRINT 
statement within a PAGE HEADER control block to 
display the page number automatically at the top of every 
page. 
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Examples 


The following example produces the column headings for 
printing the customer data across the page. 


PAGE HEADER 
PR INT "NUMBER", 
COL UMN 
12, 
"NAME", 
COLUMN 35, "LOCATION", 
COLUMN 57, 
"ZIP", 
COLUMN 65, 
"PHONE" 
SKIP 
1 LINE 


PAGE TRAILER 


Overview 


The PAGE TRAILER control block specifies what information 
appears at the bottom of each page of the report. 


Syntax 


PAGE TRAILER 
statement 


Explanation 


PAGE TRAILER 


statement 


Notes 


are required keywords. 


is an INFORMIX-4GL or FORMAT 
statement. 


1. The BOTTOM MARGIN (in the OUTPUT section) affects 
how close to the bottom of the page INFORMIX-4GL displays 
the page trailer. 


2. You cannot use the SKIP TO TOP OF PAGE statement in 
a PAGE TRAILER control block. 


3. The number of lines produced by the PAGE TRAILER 
control block may not change from page to page and must 
be unambiguously expressed. The following rules are special 
cases of this more general principle: 


• 
You cannot have a SKIP integer LINES inside a loop in 
the PAGE TRAILER control block. 
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• 
You cannot use a NEED statement in the PAGE 
TRAILER control block. 


• 
If you use an IF THEN ELSE statement in a PAGE 
TRAILER control block, the number of lines displayed 
by the PRINT statements following the THEN keyword 
must be equal to the number of lines displayed by the 
PRINT statements following the ELSE keyword. 


• 
If you use a CASE, FOR, or WHILE statement that 
contains a PRINT statement in a PAGE TRAILER con- 
trol block, you must terminate the print statement with 
a semicolon. The semicolon will suppress 
RETURI\S in the loop, keeping the number of lines in the 
header constant from page to page. 


• 
You cannot use a PRINT filename statement to read and 
display text from a file in a PAGE TRAILER control 
block. 


4. 
II\FORMIX-4GL executes the PAGE TRAILER control block 
before the PAGE HEADER control block when you issue a 
SKIP TO TOP OF PAGE statement anywhere. 


5. You can use the PAGENO expression in a PRINT 
statement within a PAGE TRAILER control block to 
display the page number automatically at the bottom of 
every page. 


Examples 


PAGE TRAILER 
PRINT COLUMN 28, 
PAGE NO USING "page ««" 
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Statements 


The control blocks determine when INFORMIX-4GL takes an 
action in a report, while the statements determine what action 
INFORMIX-4GL takes. You may use any INFORMIX-4GL statement 
in a control block, as well as a number of statements that can 
be used only in the FORMAT section of a REPORT routine. 
The most common INFORMIX-4GL statements used in reports 
are FOR, IF, LET, and WHILE. The FORMAT statements 
areas follows: 


NEED 
PAUSE 
PRINT 


PRINT FILE 
SKIP 


A description of these FORMAT-only statements follows. 
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NEED 


Overview 


This statement causes subsequent display to start on the next 
page if there is not the specified number of lines remaining on 
the current page. 


Syntax 


NEED num-expr LINES 


Explanation 


NEED 


num-expr 


LINES 


Notes 


is a required keyword. 


is an expression that evaluates to an integer 
specifying the number of lines needed. 


is a required keyword. 


1. Use the NEED statement to prevent INFORMIX-4GL from 
splitting parts of the report that you want to keep together 
on a single page. 


2. 
INFORMiX-4GL does not include the BOTTOM MARGIN 
value in the number of lines counted. 


3. If INFORMIX-4GL triggers the NEED statement in printing a 
report, it prints both the PAGE TRAILER and the PAGE 
HEADER. 


4. You may not use this statement in PAGE HEADER or 
PAGE TRAILER control blocks. 


4--17 


PAUSE 


Overview 


This statement causes output to the terminal to pause until 
you press RETUR;'I;". 


Syntax 


PAUSE [string] 


Explanation 


PAUSE 


string 


Notes 


is a required keyword. 


is an optional message that PAUSE displays. 
If you do not supply a message, PAUSE will 
not display a message. 


1. If you use a REPORT TO filename or REPORT TO 
PRINTER statement in the OUTPUT section or in the 
START REPORT statement, the PAUSE statement will 
have no effect. 
(It also will not work with the REPORT TO 
PIPE statement available on UNIX systems.) 
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Examples 


The following example will cause INFORMIX·4GL to pause while 
running the report. 


AFTER GROUP OF 
item_num 


SKIP 
TO TOP OF PAGE 
PAUSE "Press RETURN 
to cont inue" 
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PRINT 


Overview 


This statement displays information as specified in the 
OUTPUT section. 


Syntax 


PRINT [exprlist)[;] 


Explanation 


PRINT 


exprlist 


Notes 


is a required keyword. 


is an optional list of one or more expressions, 
separated by commas. 


is an optional keyword that suppresses a 
RETUR:,\ at the end of the line. 


1. One PRINT statement displays its output on one line, no 
matter how many lines the statement occupies in the report 
specification. 


2. Unless you use the keyword CLIPPED or USING following 
an expression, I:'\FORMIX-4GL displays variables with a width 
depending on their data type, as shown in FIgure 4-2. 
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Data Type 


CHAR 
DATE 
FLOAT 
SMALLINT 
INTEGER 
SMALLFLOAT 
DECIMAL 


SERIAL 
MONEY 


Default Size 


declared size . 
10 
14 (including sign and decimal point) 
6 (including sign) 
11 (including sign) 
14 (including sign and decimal point) 
number of digits plus 2 (including 
sign and decimal point) 
11 
number of digits plus 3 (including 
sign, decimal point, and dollar sign) 


Figure 4-2. Default Display Widths 


Examples 


The following example is from a mailing label report: 


FORMAT 
ON EVERY ROO 


PR INT 
f name. 
Iname 
PRINT company 
PRINT address1 
PRINT address2 
PRINT city, 
It, 
" 
, state, 
2 SPACES, 
zipcode 
SKIP 2 LINES 
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The following example is from a report that prints the 
customer list. 


FIRST PAGE 
HEADER 
PRINT 
COLUMN 30, 
"CUSTOMER LIST" 
SK IP 2 LINES 
PRINT "List jngs 
for' 
the State of" 
thisstate 
SK IP 2 LINES 
PRINT "'NUMBER", 
COLUMN 
12. 
nNAPJE". 
COLUM-J 
35. 
"LOCATION"', 
COLUMN 57. 
nZIPI1, 
COLUMN 65. 
"PHOOEu 


SK IP 1 LINE 


PAGE HEADER 
PRINT 
"NUMBER", 
COLUMN 
12. 
nNAM:", 
COLU~ 35, 
"LOCATION" 


COLUMN 57, 
"ZIP". 
COLUMN 65, 
ttPHOOE" 


SK IP 1 LINE 


ON EVERY 
ROO 


PRINT 
customer 
num 
USING 
II#1r##,I, 


COLUMN 
12, 
fname CLIPPED, 
1 SPACE, 
Iname 
CLIPPED, 
COLU~ 35. 
city 
CLIPPED, 
tI 
tt. 
state. 
COLUMN S7, 
z,peode, 
COLUMN 65. 
phone 
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PRINT FILE 


Overview 


This statement displays the contents of a text file in a report. 


Syntax 


PRIl':T FILE "filename" 


Explanation 


PRINT FILE 
are required keyv;ords. 


filename 
is a required filename that can be a pathname. 
You must enclose the filename in quotation 
marks. 


Notes 


1. You can use the PRINT FILE statement to include the 
body of a form letter in a report that generates custom 
letters. 
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SKIP 


Overview 


This statement skips lines in a report or skips to the top of the 
next page. 


Syntax 


SKIP linteger LINE[S] I TO TOP OF PAGE: 


Explanation 


SKIP 


integer 


LINES 


TO TOP 
OF PAGE 


Notes 


is a required keyv.'ord. 


is an integer specifying the number of lines to 
skip. 


is an optional keyword. You can use the 
keyword LINE in place of LINES if you like. 


are optional keywords. 


1. You cannot use a SKIP LINES statement inside a CASE, 
FOR, or WHILE statement. 


2. You cannot use a SKIP TO TOP OF PAGE statement in a 
FIRST PAGE HEADER, PAGE HEADER, or PAGE 
TRAILER control block. 
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Examples 


The following example is from a report that prints the 
customer list. 


FIRST 
PAGE 
HEADER 
PRINT 
COLUMN 
30, 
"CUSTOMER LIST" 
SK I P 
2 
LINES 
PR I NT 
"L j 5 t j n 9 5 
tor 
the 
5 tat e 
0 f" 
t his s t 8 t e 
SKIP 
2 
LINES 
PR I NT 
"NUMBER", 
COLUMN 
12, 
"NAIJE", 
COLUMN 
35, 
"LOCAT I ON", 
COLUMN 
57, 
"Z'I P", 
COLUMN 65, 
"PHONE" 
SK I P 
1 LINE 


PAGE 
HEADER 
PRINT 
"NUMBER", 
COLUMN 
12, 
"NAIJE", 
COLUMN 
35, 
"LOCATION", 
COLUMN 
57, 
"ZIP", 
COLUMN 65, 
"PHONE" 
SK I P 
1 LINE 


ON EVERY 
RON 


PR I NT 
Cu 5 t orne r 
n um 
US I NG "####1'. 


COLUMN 
12, 
f na;;;e 
CL I PPED, 
1 SPACE, 
I n arne 
CL I PPED. 
COLLIM'J 
35. 
cit y 
CL I PPED, 
n. 
" 
, 
s tat e , 
COLUMN 
57, 
zipcode, 
COLUMN 
65, 
phone 


The following example is from a mailing label report. 


FORMAT 
ON 
EVERY 
RON 


IF 
(c i Iy 
IS 
NOT NULL) 
AND (slate 
IS NOT NULL) 
THEN 
PR I NT 
f name 
CL I PPED, 
1 SPACE, 
I name 
PRINT 
company 
PRINT addressl 
IF 
(address2 
IS 
NOT NULL) 
THEN 
PRINT 
address2 
PRINT city CLIPPED,",", 
state, 
2 
SPACES, 
z.ipcode 
SKIP 
TO 
TOP 
OF 
PAGE 
END 
IF 


Expressions and Built-in Functions 


Expressions used within REPORT routines have the same 
syntax as expressions used elsewhere in INFORMIX-4GL. These 
expressions may use the functions defined in Chapter 1. You 
may also use the built-in aggregate functions. The aggregates 
in reports have a slightly different application from those used 
in a SELECT statement. These differences are described in 
the next pages. There are also built-in functions that you may 
use only in REPORT routines. The table below lists all the 
functions you may use in a REPORT routine. 


ASCIIa 


AVGfS 


CLIPPEDa 
COLUMNa 
COUNT(*{S 
DATEa 


DATEOa 
DAYOa 
GROUpf 
LINENOf 
MAXfS 


MINfS 


MDyoa 
MONTH(t 
PAGENO 
PERCENT(*)f 
SPACESa 


SUMfS 


TIMEa 
TODAya 


USINGa 
WEEKDAYOa· 
YEAROa 


r 
You can use these functions only within the FORMAT 
section of a REPORT routine. A description of these 
functions follows. 


rs You can use these functions only within the FORMAT 
section of a REPORT routine or in INSERT,SELECT, or 
UPDATE statements elsewhere. They are described both in 
the following pages and in Chapter 7. 


a 
These functions are described in Chapter 1. 
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Aggregates 


Overview 


Aggregates allow you to summarize information in a report. 


Syntax 


[GROUP) 
ICOUNT(*) I PERCENT(*) I ISUM I AVG I MIN I MAX:(exprJ): 
[\VHERE expr2) 


Explanation 


GROUP 
is an optional keyword that causes the aggre- 
gate to reflect information for a specific group 
only. You can only use this keyword in an 
AFTER GROUP OF control block. 


COUNT(*) 
is a keyword. This keyword is always 
evaluated as the total number of rows qualified 
by the optional WHERE clause. 


PERCENT(*) 
is the keyword that evaluates COUNT as a 
percent of the total number of rows in the 
report. 


SUM 
evaluates as the total of expr1 in the rows 
qualified by the optional WHERE clause. 
SUM ignores rows with NULL value for expr1; 
it returns NULL if all rows have a NULL 
value for expr1. 


AVG 
evaluates as the average of expr1 in the rows 
qualified by the optional WHERE clause. 
AVG ignores rows with NULL value for expr1; 
it returns NULL if all rows have a NULL 
value for expr1. 
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IvIIN 


MAX 


expr1 


WHERE 


expr2 


Notes 


evaluates as the minimum of expr1 in the rows 
qualified by the optional WHERE clause. 
MIN ignores rows with NULL value for expr1; 
it returns NULL· if all rows have a NULL 
value for exprl. 


evaluates as the maximum of exprl in the rows 
qualified by the optional WHERE clause. 
MAX ignores rows with NULL value for expr1; 
it returns NULL if all rows have a NULL 
value for expr1. 


is the expression that SUM, AVG, MIN, and 
MAX evaluate. It is typically a numeric vari- 
able or a numeric expression that includes a 
numeric variable. 


is an optional keyword. 


is a Boolean expression that qualifies the 
aggregate. 


1. The WHERE clause allows you to select among the rows 
passed to the report. 
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Examples 


ON 
EVERY 
RON 


PRINT 
snum 
USING n###". 
COLlJtvt-J 
10. 
manu_code. 
COLUMN· 18. 
des c rip t Ion 
CL IFPED. 
COLUMN 
38. 
Q U8 n 1 I t Y US I NG 
"##~I. 


COLUMN 
43, 
unitJrice 
USING h$$$$ 
&&". 
COLUMN 55, 
tot.IJrice 
USING h$$,$$$,$$$.&&" 


AFTER 
GROUP 
OF 
number 
SKIP 
1 
LINE 
PRINT 
4 
SPACES, 
"Shipping 
charges 
for 
the 
order: 
ship_charge USING "$$$$ 
&&11 
SKIP 
1 LINE 
PRINT 
5 
SPACES, 
"Tota I 
amount 
for 
the 
order: 
ship_.charge +'GROUP SUM(tot.'Jrice) 
USING "$$,$$$,$$$.&&" 
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LINENO 


Overview 


This expression has the value of the line number of the report 
line that INFORMIX-4GL is currently printing. INFORMIX-4GL 
computes the line number by calculating the number of lines 
from the top of the page including the TOP MARGIN. 


Syntax 


LINENO 


Explanation 


LINENO 


Examples 


is a required keyword. 


PRINT COLUMN 
10, 
LINENO USING "Line «<" 
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PAGENO 


Overview 


This expression has the value of the page number of the page 
that INFORMIX-4GL is currently printing. 


Syntax 


PAGENO 


Explanation 


PAGENO 


Notes 


is a required keyword. 


'- 


1. Use PAGENO in a PRINT statement in the PAGE 
HEADER or PAGE TRAILER control block to number the 
pages of a report. (You can also use PAGENO in other 
control blocks.) 


Examples 


PAGE TRAILER 
PRINT COLUMN 28, 
PAGE NO USING "page ««" 
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TIME 


Overview 


This expression evaluates as a character string with a value of 
the current time in the format hh:mm:ss. 


Syntax 


TI!\1E 


Explanation 
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TIME 
is a required key\','ord. 


Chapter 5 


4GL Function Library 
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Chapter Overview 


This chapter describes functions that are available from the 
Il'\FORMIX-4GL library. You can call any of the functions listed 
in the following table and the INFORMIX-4GL compiler auto- 
matically links them in the final program. 


Function 


arg_val 
arr_count 
arr 
curr 
downshift 
err-'print 
err_get 
err_quit 
errorlog 
infield 
length 
num_args 
scr_line 
set 
count 
showhelp 
startlog 
upshift 


Return Value or Effect 


Command line argument 
Total filled rows of program array 
Current row of program array 
Lowers case of string argument 
Prints 4GL error message on ERROR line 
Prints 4GL error message to string variable 
Prints4GL error message and exits 
Appends argument to error log 
True if argument is current field 
Length in bytes of string argument 
Number of command line arguments 
Current row of screen array 
Sets number of rows of program array 
Displays help message 
Opens error log file 
Raises case of string argument 


These functions are described more fully in the following pages. 
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ARG_VAL 


Overview 


arg_val returns a command line argument as a CHAR 
variable. 


Syntax 


arg_\'al(expr) 


Explanation 


expr 


Notes 


is an integer expression. 


1. arg_val(n) returns the nth command line argument as a 
CHAR variable. 


2. The value of expr must be between 0 and num_args 0, 
the number of command line arguments. arg_val(O) is 
your program name. 


3. arg_val and num_args allow you to pass data to the 
program from the command line that executes the program. 
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Examples 


If your compiled executable 4GL program name is rnyprog and 
you executed the command line 


myprog 
john maryellen 
joe frank 


the following program segment puts the names you entered into 
an array of CHAR variables. 


DEFINE args ARRAY[8] 
OF CHAR(10). 
i 
SMALLINT 


FOR 
i 
1 TO num args() 
LET args[ i] ~ arg_val (i) 
END FOR 


Related Functions 


NUM 
ARGS 
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ARR 
COUNT 


Overview 


arr_count returns the number of rows that are entered in a 
program array during or after an INPUT ARRAY statement. 


Syntax 


Notes 


1. You can use arr 
count to record the number of rows 
currently stored in a program array. 


2. If you execute a statement in a BEFORE, AFTER, or ON 
KEY clause that changes the value of arr_curr, scr_line, 
or arr 
count, the new value remains for the duration of 
the clause (unless changed again.) After INFORMIX-4GL exe- 
cutes the last statement in the clause, INFORMIX-4GL restores 
the original value. 
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Examples 


FUNCTION 
insert_items() 
DEFINE counter SMALLINT 
FOR counter = 1 TO arr_count() 
INSERT 
INTO 
items 
VALUES 
(p_items[counter]. item_num, 
p_orders.order_num, 
p_i t ems [coun t er]. st oCk_num, 
p_i tems[counter J.manu_code, 
p_items [ co un t e r ] . qua n tit y . 
p_i tems[counter]. totaLJH ice) 
END FOR 
END FUNCTION 


Related Functions 


ARR_CURR, SCR_LINE 
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ARR 
CURR 


Overview 


arr_curr returns the row ofthe program array that corre- 
sponds to the current screen array row during or immediately 
after an INPUT ARRAY or DISPLAY ARRAY statement. 


Syntax 


Notes 


1. The current screen row is the row where the cursor is 
located at the beginning of a BEFORE ROW or AFTER 
ROW clause. 


2. The first row of both the program array and the screen 
array is numbered 1. 


3. If you execute a statement in a BEFORE, AFTER, 01' ON 
KEY clause that changes the value of arr_curr, scr_line, 
or arr_count, the new value remains for the duration of 
the clause (unless changed again.) After INFORMIX-4GL exe- 
cutes the last statement in the clause, INFORMIX-4GL restores 
the original value. 
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For example, if the DISPLAY ARRAY statement in the 
following INPUT ARRAY statement changes the value of 
arr_ curr from 1 to 4, the value remains 4 for the rest of 
the ON KEY clause. After INFORMIX-4GL executes the 
MESSAGE statement, it resets arr_curr to 1, its prior 
value. 


INPUT 
ARRAY 
P~I terns 
to s_items 
• 
ON KEY 
(F6) 
DISPLAY ARRAY p_stock to s_stock.· 
END DISPLAY 
LET 
ps_curr = arr_curr() 
MESSAGE 
"The 
current 
value 
of 
arr_curr 
is: 
n 
p8_curr 
END 
INPUT 


Examples 


The following example tests the user input and rejects it if the 
customer is not from California. (See the definition of 
scr 
lineO.) 


DEFINE p_array ARRAY:90 
OF RECORD 
fname 
CHAR(15). 
Inarne 
CHAR ( 15) . 
slale 
CHAR(2) 
END RECORD. 
ps_curr, 
sc_curr SMALLINT 


INPUT 
ARRAY p_srray' FRW sef_srray'. 
AFTER FIELD slale 
LET 
pa_curr 
= err_curr() 
LET 
se 
curr 
= 
ser 
I ine() 
IF upshift'(p_SrraYLPs_curr].state) 
!= nCAn 
THEN 
ERROR "Customers must 
be 
f rom Cal i forn i 8" 


INITIALIZE 
p_8r·r8yrp8_curr~.· TO NULL 
CLEAR 
se '_B r ray 
~ se_cu r r~, .• 
NEXT FIELD 
fname 
END 
IF 
END 
INPUT 


Related Functions 
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DOWNSHIFT 


Overview 


downshift returns a string in which all uppercase characters in 
its argument are converted to lowercase. 


Syntax 


downshift(str) 


Explanation 


str 
is a string constant or a variable of type CHAR. 


Notes 


1. Non-alphabetic characters in str are not altered. 


2. You can use the downshift function in an expression (when 
such usage is allowed) or assign the value returned by the 
function to a variable. 


Examples 


LET d_str = downshift(str) 


Related Functions 


UPSHIFT 
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ERR 
GET 


Overview 


err_g"et returns a CHAR variable which contains the 
INFORMIX-4GL error message corresponding to its argument. 


Syntax 


err_get(expr) 


Explanation 


expr 


Notes 


is an integer expression. 


1. expr is usually the global status variable. 


2. err_get is most useful during debugging. The message 
it returns is probably not helpful to the user of your 
application. 


Examples 


IF 
status < 0 THEN 
LET errtext 
= 
err_get(status) 
END 
IF 


Related Functions 


ERR_PRINT, ERR_QUIT, STARTLOG 
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ERR 
PRINT 


Overview 


err~rint prints the INFORMIX·4GL error message 
corresponding to its argument on the Error Line. 


Syntax 


call err-----'print(expr) 


Explanation 


expr 


Notes 


is an integer expression. 


,'.\ 


1. 
expr is usually the global status variable. 


2. err~rint is most useful during debugging. The message 
it returns is probably not helpful to the user of your 
application. 


Examples 


IF 
status < 0 THEN 
CA L L err-----.p r i n t ( s tat us) 
END 
IF 


Related Functions 


ERR_GET, ERR_QUIT, STARTLOG 


5-14 Chapter Overview 


ERR_QUIT 


Overview 


err_quit prints the INFORMIX-4GL error message correspond- 
ing to its argument on the Error Line and then terminates the 
program. 


Syntax 


CALL err_quit(expr) 


Explanation 


CALL 


expr 


Notes 


is a required keyword. 


is an integer expression. 


1. 
expr is usually the global status variable. 


2. err_quit is most useful during debugging. The message it 
returns is probably not helpful to the user of your 
application. 


Examples 


IF status' 
0 
THEN 
CALL 
er r_qu II (stat us) 


ENe 
IF 


Related Functions 


ERR_GET, ERR_PRINT, STARTLOG 
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ERRORLOG 


Overview 


errorlog writes its argument to the current error log file. 


Syntax 


CALL errorlog(str) 


Explanation 


CALL 


str 


Notes 


is a required keyword. 


is a string constant or a CHAR variable. 


1. The error log file is created by the startlog function. 


2. If str is not a CHAR variable nor a string constant, 
INFORMIX-4GL will convert it to a string. 


3. The primary use for the errorlog function is debugging and 
customized error handling. 
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Examples 


CALL 
start 10g("/usrlsteve/error. log") 


FUNCTION start__menu() 
CALL 
error 10g("Enter ing 
start--!'1enu 
funct ion") 


Related Functions 
STARTLOG 
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INFIELD 


Overview 


The infield function tests whether its argument is the current 
screen field. 


Syntax 


infield(field-name) 


Explanation 


field-name is the name of a screen field. 


Notes 


L infield is a Boolean function that returns the value true 
if field-name is the name of the current screen field and 
otherwise returns the value false. 


2. Use infield during an INPUT or INPUT ARRAY 
statement to take field-dependent actions. 


3. Outside of the INPUT or INPUT ARRAY statement, 
infield returns a value corresponding to the field that was 
current when the user terminated the INPUT or INPUT 
ARRAY statement. 
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Examples 


The following example uses infield along with showhelp to 
give field-dependent help messages. 


INPUT p_rec.· 
FROv1 sc rec.· 
ON KEY (CONTROL-B) 
CASE 


w-lEN 
i n fie I d ( fie I d 1 ) 
CALL showhelp(101) 


w-lEN 
inf ield(f ield2) 
CALL showhelp(102) 


w-lEN 
i n fie I d ( fie I d 3) 
CALL showhelp(103) 


END CASE 
END 
INPUT 
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LENGTH 


Overview 


The length function returns the number of bytes in its string 
argument after deleting all trailing spaces. 


Syntax 


Iength(str) 


Explanation 


str 
is a string constant or a CHAR variable. 


Examples 


The following example, taken from the FORMAT section of a 
report, centers a title on an 80-column page. 


LET tit Ie = "Invoice 
for 
It, 
fnarne 
CLIPPED, 
" ", 
I n arne 
CL I PPED 
LET offset = (80 - 
length(title»/2 
PRINT 
COLUMN offset, 
title 


5-20 Chapter Overview 


NUM_ARGS 


Overview 


num_args returns the number of arguments on the 
command line. 


Syntax 


Notes 


1. You may design your program to expect or allow arguments 
after the name of the executable program. The num_args 
function tells you how many arguments were on the line, in 
addition to the program name, and the arg_val function 
retrieves the individual arguments. 


Examples 


If your compiled, executable 4GL program name is myprog and 
you executed the command line 


myprog 
john maryellen 
joe 
frank 


the following program segment puts the names you entered into 
an array of CHAR variables. 


DEFINE 
args 
ARRAY:S: 
OF CHAR(,O). 
SMALL I NT 


FOR 
i = 
1 TO 
n urr~a r 9 s ( ) 
LET args: i! = arg_val(i) 
END 
FOR 
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Related Functions 


ARG 
VAL 
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( 


SCR_LINE 


Overview 


scr_line returns the number of the current screen row during 
an INPUT ARRAY statement. 


Syntax 


Notes 


1. The current screen row is the rO\\7 where the cursor is 
located at the beginning of a BEFORE RO\\- or AFTER 
ROW clause. 


2. The first row of both the program array and the screen 
array is numbered 1. 


3. If you execute a statement in a BEFORE, AFTER, or ON 


KEY clause that changes the value of arr_curr, scr_line, 
or arr_count, the new value remains for the duration of 
the clause (unless changed again.) AfterINFORMIX.4GL exe- 
cutes the last statement in the clause, INFORMIX·4GL restores 
the original value. 
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Examples 


The following example tests the user input and rejects it if the 
customer is not from California. (See the definition of 
arr_currO.) 


DEFINE p_array ARRAYl90J 
OF RECORD 
fname 
CHAR(15), 
I name 
CHAR ( 15) , 
state 
CHAR(2) 
END RECORD, 
pa_curr, 
sc_curr 
SMALLINT 


INPUT ARRAY p_array 
FROvl scr_array.* 
AFTER FIELD state 
LET pa_curr 
= arr_curr() 
LET sc_cur r 
= 
scr_1 i ne() 
IF upshift(p_array:pa_curr:.state) 
!= "CA" THEN 
ERROR "Customers must 
be 
from California" 
INITIALIZE p_arrayLpa_currJ.* 
TO NULL 
CLEAR scr_array[sc_currJ.* 
NEXT FIELD 
fname 
END 
IF 
END 
INPUT 


Related Functions 
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SET 
COUNT 


Overview 


set 
count tells INFORMIX-4GL the number of filled rows in a 
program array. 


Syntax 


CALL set_count(exprl 


Explanation 


CALL 


expr 


Notes 


is a required keyword. 


is an integer expression. 


1. Before you use the INPUT ARRAY WITHOUT 
DEFAULTS or the DISPLAY ARRAY statement, you must 
call the set_count function with an argument that is the 
total number of filled rows in the program array. This 
allows the program to know the initial value to return for 
arr 
count. 
' 


Examples 


CALL sel 
counl (23) 
INPUT 
ARRAY 
P array WITHOUT 
DEFAULTS 


FROv1 
s~a r~a y .• 


Related Functions 


ARR_COUNT 
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SHOWHELP 


Overview 


showhelp displays a help screen and restores the previous 
screen when completed. 


Syntax 


CALL showhelplnexpr) 


Explanation 


CALL 


nexpr 


Notes 


is a required keyword. 


is an integer expression. 


1. \Vhen called with an argument that is the number of a help 
message in the help file named in an OPTIONS statement, 
showhelp clears the screen, displays the help message, and 
presents the user with a menu of help options. When the 
user selects Resume from the help menu, the previous 
screen is restored. 


2. See Appendix G for assistance in setting up a help file. 
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Examples 


The following example uses infield along with showhelp to 
give field-dependent help messages. 


INPUT p_rec.* 
FRQv1 sc_rec.* 
ON KEY(CONTROL-B) 
CASE 


\M-lEN 
i nfie Id ( fie Id 1) 
CALL showhelp(101) 


\M-lEN 
i n f ie Id ( fie Id2) 
CALL showhelp(102) 


\M-lEN 
inf ield(f ield3) 
CALL showhelp(103) 


END CASE 
END 
INPUT 
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STARTLOG 


Overview 


startlog opens an error log file. 


Syntax 


CALL startlog(filename) 


Explanation 


CALL 


filename 


Notes 


is a required ke~'\\'ord. 


is a quoted string or CHAR variable that evalu- 
ates to the name of the error log file. 


1. If the file specified by filename does not exist, startlog will 
create it. If the file does exist, startlog will open the file 
and position the file pointer so that subsequent errors will 
be appended to the end of the file. 


2. If you do not want the error log file to reside in the current 
directory, you must specify a full pathname. 


3. After you call the startlog function, a: record of every sub- 
sequent error that occurs during the execution of your 4GL 
program will be written to the error log file. 


4. The error record will consist of the date, the time, the 
source module name and line number, the error number, 
and the error message. 


u. You may write your own messages to the error log file by 
using the errorlog function. 
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\.. 


Examples 


CALL startlog("/usrlsteve/error. log") 


FUNCTION 
start_menu() 
CALL error log("Enter ing start 
menu 
funct ion") 


Related Functions 


ERRORLOG 


UPSHIFT 


Overview 


upshift returns a string in which all lowercase characters in its 
argument are converted to uppercase. 


Syntax 


upshift (str) 


Explanation 


8tr 
is a string constant or a variable of t)Ve CHAR. 


Notes 


1. 
Non-alphabetic characters in str are not altered. 


2. 
You can use the upshift function in an expression (when 
such usage is allowed) or assign the value returned by the 
function to a varaible. 


Examples 


LET 
u_str 
= 
upshift(str) 


Related Functions 


DOWNSHIFT 


\- 
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6-2 


Chapter 6 Table of Contents 


Chapter Overview 
. 


The INFORI\lIX-4GL Menu 
. 


The MODULE Design Menu 
.. 
The Modify Option 
: 
.. 
The New Option 
.. 
The Compile Option 
. 
The Program_Compile Option 
; 
.. 
The Run Option 
. 
The Exit Option 
. 


The FORI\1 Design I\1enu 
. 
The Modify Option 
: 
.. 
The Generate Option 
. 
The New Option 
. 
The Compile Option 
. 
The Exit Option 
. 


The PROGRAM Design Menu 
.. 
The Modify Option 
. 
The New Option 
. 
The Compile Option 
'" 
. 
The Planned_Compile Option 
.. 
The Run Option 
.. 
The Drop Option 
. 
The Exit Option 
. 


The QUERY LANGUAGE Menu 
. 


5 


6 


7 
7 
10 
10 
11 
11 
12 


1::: 
12 
14 
14 
15 
15 


Ie 
16 
18 
10c' 
20 
21 
21 
22 


22 


6-3 


6-4 


Chapter Overview 


INFORMIX-4GL provides a Programmer's Environment that con- 
sis!s of a series of nested menus. The philosophy behind the 
menu structure is that you should be able to move among the 
various steps of program development and the design of screen 
forms in a way that supports the design process. The 
INFORMIX-4GL Programmer's Environment anticipates the steps 
of development and keeps track of the components of your 
application. To enter the Programmer's Environment, type 


j 4 9 I in response to the system prompt. 


If you desire, you can invoke the compilers and editor directly 
from the operating system prompt and not use the Program- 
mer's Environment. See Chapter 1 for a description of the 
proper command line syntax. 
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The INFORMIX-4GL Menu 


At the top level, you have five options: 


Module 
Work on an INFORMIX-4GL program 
module. 


Form 
Work on a screen form. 


Program 
Describe components of a multi-module 
program. 


Query_language 
Use the RDSQL interactive interface. 


Exit 
Return to the operating system. 


Putting these options at the top anticipates that you enter the 
INFORMIX-4GL environment with one of the three development 
areas in mind. 


INFORMrX·4GL 
M25LLLJ.~: 
Form 
Program 
Query- language 
Ex I t 
Create. 
modify 
or 
run 
Individual 
4GL 
program modules 


- .. 
- 
- 
·Press 
CTRl·W for Help-····· 


You select an option from the menu in either of two ways: by 
typing the first letter of the option or by using the SPACEBAR or 
ARROW keys to move the cursor to the option you want and 
pressing RETURN. 
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The MODULE Design Menu 


There are two kinds of program files: main modules (containing 
at least the MAIN routine) and auxiliary modules (containing 
FUNCTION or REPORT routines only). You select the 
Module option to work on either of these. 


After you select the Module option, you have the following 
options: 


Modify 
Change an existing 4GL program 
module. 


New 
Create a new 4GL program module. 


Compile 
Compile an existing 4GL program 
module. 


Program_Compile 
Compile a 4GL application program. 


Run 
Run an existing 4GL program module or 
application program. 


Exit 
Return to the INFORMIX-4GL Menu. 


The Modify Option 


Make changes to an existing 4GL program module. 


MJDULE:~; 
New 
Compile 
Program_Compile 
Run 
Exit 
Change 
an exist ing 
4GL 
program module . 


................................ 
·····Press 
CTRL·W for 
Help· 
. 


6-7 


If you select this option, INFORMIX-4GL requests a name for the 
file and then prompts you to name your editor. If you have 
designated an editor with the DBEDIT environment variable 
(see Appendix C) or named an editor previously in this session, 


I~FORMIX-4GL takes you immediately to your editor with the 
file that you named. The file being edited becomes the current 
file. 
When you leave the editor, INFORMIX-4GL moves to the 
MODIFY MODULE Menu with the Compile option 
highlighted. 


MJD1FY 
MJDUlE 
~j)_~.pII!~ 
Save-and-exit 
Discard'and-exil 
Comp 
I Ie 
the 
4GL 
module 
speci f icst ion 


--Press 
CTRL·W for 
H~lp· ..... 


If you select the Compile option. I~FOR~nX-4GL displays the 
COMPILE MODULE Menu: 


COMPILE MODULE 
~ec~ 
Runable 
Ex;! 
Creale 
object 
file 
only. 
no 
linking 
to 
occur 


·Press CTRl·W for 
Help· .... - 
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The Object option creates a .0 file and makes no attempt to 
link the file with other files. The Runable option assumes that 
the current program module is a complete 4GL program and 
that no other module needs to be linked to it. If this is not 
the case, then you should use the Object option. 


If there are compilation errors, INFORMIX-4GL presents the 
following menu: 


Ca.-lP I L E MODUL E 
igo rr eo]> 
Ex; I 
Correct 
errors 
in 
the 
4GL module. 


········ __ · __ ·····································Press CTRL·W for Help······ 


If you choose to correct the errors, INFORMIX-4GL puts you into 
your editor with a copy of your source module containing 
embedded error messages. Make corrections to your source file, 
save your changes, and leave your editor. You do not have to 
erase the error messages; INFORMIX-4GL will do it for you. You 
return to the previous MODIFY MODULE Menu to choose 
whether to compile or to save or discard your changes. 


If there are no compilation errors, INFORMIX-4GL presents the 
MODIFY MODULE Menu with the Save-and-Exit option 
highlighted. If you select this option, INFORMIX-4GL writes the 
current file (the source file) to disk with the filename extension 
Agl. It writes the object file to disk with the extension .0, 
or writes the executable file to disk with the filename 
extension Age. If you select the Discard-and-Exit option, 
Il'IFORMIX-4GL discards any changes made since you selected the 
Modify option and leaves your files as they were previously. 
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The New Option 


Create a new main or auxiliary module. This option is similar 
to the Modify option, except that the submenu is titled NEW 
MODULE. INFORMIX-4GL does not list the names of existing 
modules, but asks you to enter a new module name instead. 
If you have not designated an editor with DBEDIT or named 
an editor previously in this session, INFORMIX-4GL prompts you 
for one. It then puts you into the editor. 


MJDULE 
MOdify 
~~ 
Compile 
Program_Compile 
Run 
Exil 


Crea1~ 
a 
new 
4GL 
program module 


----·.········.····························Press 
CTRL·W for Help-···· 


The Compile Option 


Compile a program module. This option allows you to compile 
a program module without having first to select the Modify , 
option. 


OOOULE 
Modify 
New 
~pile' 
Program_Compile 
Run 
Exit 
Campi Ie 
an 
eXist ing 
4GL 
program module. 


·---······------····--·········--·············Press 
CTRL·W for Help-···· 


After receiving the name of the program module to compile, 
I;\FORMIX·4GL goes to the COMPILE l\fODULE Menu that 
gives you the options of Object, Runable, or Exit. From 
there the situation is the same as described earlier for the 
Modify option. 
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The Program_Compile Option 


The Program_Compile option of the MODULE Menu is the 
same as the Compile option of the PROGRAM Menu (see thE;! 
option for details). It permits you to compile and link modules 
as described in the program specification database, taking into 
account the time when the modules were last updated. This 
option is useful when you have just modified a single module of 
a complex program and want to test it by compiling and linkinf: 
it with the other modules. 


Note: 
If you are running a DOS system on MS-NET, there 
are certain procedures you must follow if you want to compile 
an INFORMIX-4GL program. See the section "Compiling and 
Executing Programs" in Chapter 1 of the INFORMIX-4GL 
Reference Manual for information on how to do this. 


The Run Option 


Run a compiled program. 


MODULE: 
Modify 
New 
Compi Ie 
Progrem_Compi Ie 
~ 
Exit 
Execute 
an 
exiat ing 
4Gl 
program module or 
appl iest ion 
program. 


·················································Pre•• CTRL·W lor Help···-·· 


The RUN PROGRAM screen presents a list of compiled 
modules (which could be a program) with the highlight on thE 
module corresponding to the current file, if any. A compiled 
program must have the extension Age to be included in the 
list. If you compile a program outside the Programmer's 
Environment and want it to appear in this list in the future, 
give the executable file the extension Age. If no compiled 
programs exist, INFORMIX-4GL prints an error message and 
returns you to the MODULE Menu. 
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The Exit Option, 


Return to the INFORMIX-4GL Menu. 


MODULE: Modify 
N.w 
Campi I. 
Progr.m_Compi I. 
Run 
~ 


R.turns 
to 
the 
INFORMIX·4GL M.nu, 
...•.......... : 
Pr ••• CTRL·W for H.lp······ 


The FORM Design Menu 


You can generate, modify, and compile screen forms through 
the FORM Menu. Select the Form option from the 
INFORMIX-4GL Menu to view the FORM Menu. 


The Modify Option 


The Modify option of the FORM Menu is very similar to that 
option in the MODULE Menu. 


FORM', 
~ 
G.n.r.t. 
N.w 
Campi I. 
Exit 
Change 
an 
ex iet ing 
form epeci f ie8t ion . 
................................................ ·Pr••• CTRL·W for H.lp· .. · .. 


6-12 The FORM Design Menu 


If you select this option, the Programmer's Environment asks 
you for the name of the form specification file you want to 
modify and places you in the editor. When you leave the 
editor, I],;FOR~flX-4GL presents you with the MODIFY FORM 
Menu with the Compile option highlighted. 


tvt8DIFY 
FOFf,.~ 
lCo~R~~~ 
Save·and-exit 
Discard-snd·e).it 
Camp i Ie 
the 
form 
spec i f icat ion. 


·········--·-_·······························Press CTRL·W for Help······ 


If there are compilation errors, II'\FOR~tIX·4GL presents you with 
the COMPILE FORI\-1 Menu: 


COvlP I LE 
FOFM 
Co r _~~_l. 
E x I t 


C::<rrect 
efrors 
In 
the 
form speci f ice! ion. 


···----··································Press CTRL-V'.'.for Help······ 


After you correct your errors (you do not have to delete the 
error messages), INFORMIX·4GL returns you to the MODIFY 
FORM Menu with the Compile option highlighted. 


If there were no compilation errors, you may choose whether to 
save the modified form specification file and the compiled form 
or to discard the changes and return to the state before you 
chose to modify the form specification file. 
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The Generate Option 


When you select the Generate option, INF'ORMIX-4GL asks you 
to select a database, choose a name for the form, and choose 
the names of tables. INFORMIX·4GL then runs the -d option of 
FORM4GL to create and compile a default form. 


FORv1 
Mod i f y 
lGe"ner"s-l-e". 
New 
Camp i I e 
Ex i t 
Generate 
and 
campi Ie 
a default 
form speci f ieat ion 


··················_······························Press CTRL·W tor Help······· 


The New Option 


The New option of the FORM Menu allows you to create a 
form from scratch without going through the Generate option. 


FORM 
Modi fy 
Genera1e 
~ 
Campi Ie 
Exit 
Create 
a 
new 
form 
spec i f ieat ron. 


·.·.···································-------···Press CTRL·W for Help······ 


After asking you for the name of your form specification 
file, I2\'FOR!\lIX-4GL places you in th~ editor where you can 
create a form specification file. When you leave the editor. 
INFORMIX-4GL transfers you to the NEW FORM Menu that is 
like the MODIFY FORM Menu. You may compile your form 
and correct it in the same way. 
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The Compile Option 


The Compile option allows you to compile an existing form 
specification file without having to go through the Modify 
option. INFORMIX-4GL asks you for the name of the form 
specification file and then performs the compilation. If compi- 
lation is not successful, INFORMIX-4GL presents the COMPILE 
FORM Menu with the highlight on the Correct option. 


FO~~ 
Modi Iy 
Generate 
New 
eo~~i Ie 
Exit 


Com~ile 
an 
existing 
form specification 


. _ 
- - _ 
- ........................•... ·Press 
CTRL·W for Help-····· 


The Exit Option 


The Exit option returns you to the INFORMIX-4GL Menu. 


FORM 
Modi fy 
Gene'alE 
New 
Campi Ie 
~: 


Returns 
to 
the 
lNFORMIX·4GL Menu 


-_······-_······································Press CTRL·Y-' for Help······ 


The PROGRAM Design Menu 


If you select the Program option from the INFORMIX-4GL 
Menu. INFORl\nX~4GLsearches your DBPATH (see Appendix C) 
to determine whether the program specification database 
(syspgrn4gl) exists. The program specification database 
describes the modules and compiler options that constitute 
your entire INFORMIX-4GL program. If the database does not 
exist, Il\'FORMIX-4GL asks you whether you want to create one. 
If you enter y in response to the prompt, INFORMIX-4GL creates 
the syspgm4g1 database, grants CONNECT privilege to 
PUBLIC, and presents you with the PROGRAM Menu. As 
Database Administrator of syspgrn4gl, you may restrict other 
users' access later. If syspgrn4g1 already exists, I]'I;FORMIX-4GL 
takes you immediately to the PROGRAl\l J\1enu. 


From the PROGRAM Menu you can create or modify informa- 
tion in a program specification, compile and link your program, 
and run your program. 


The Modify Option 


The Modify option allows you to modify the data in an 
existing program specification. 


PROGRAM. 
~q_~)'y_ 
N'ew 
Compile 
Planned_Compile 
Run 
Drop 
E,x11 


Change 
the 
compilation definition 
of 
a 
4GL 
applIcation 
program 


····_-·--··········_~··-···_·_·--_···············Press 
CTRl-W lor 
Help- 


Note: You can select the Modify option only if a program 
specification exists. If no program specification exists, you may 
create one by selecting the New option. 
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I~FORMIX-4GL asks you to indicate the name of the program 
specification you want to modify. It then invokes a screen and 
menu allowing you to update the information in the program 
specification database: 


MODIFY 
PROGRAM 
~. 
Other 
Libraries 
Campi Ie_Opt ions 
Rename 
Exit 
Edi t 
the 
4GL 
sources 
list . 


................................................ ·Press 
CTRL·W for Help······ 
Program 
:myprog 


4g1 
Source 
main 
. fun c t 
: rep t 


4g1 
Source Path 
: JU:John 
appf.4GL 


.:u 
john 
appll4GL 
U' johnisppi i4GL 


Other 
Source 
Ext 
.cfunc 
.c 


Librar ies 
"m 


Other Source Path 


; lUi john/appl/C 


Camp i I e 
Op t ion 5 


Figure 6-1. Sample Entry in Program Specification 


In Figure 6-1, you named the program myprog. You could 
change this name by selecting the Rename option. The 
significance of the program name is that the executable pro- 
gram resulting from compiling and linking all the source files 
and libraries has the program name with the extension Age. 
In this case, the executable program has the name 
myprogAge. 


The 4GL option allows you to update the entries for 4GL 
Source and 4GL Source Path. The five rows of fields under 
these labels form a screen array and, when you select the 4GL 
option, INFORMIX-4GL executes an INPUT ARRAY statement to 
allow you to move through the array (and to scroll for entries 
up to a maximum of 30). See the INPUT ARRAY statement 
in Chapter 7 for how to use your function keys to scroll, delete 
rows, and to insert new rows (you cannot redefine the function 
keys as you can with a 4GL program). 
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In the example shown in Figure 6-1, you have chosen to break 
up your 4GL source program into three modules: a module con- 
taining your main program (mainAgI), a module containing 
functions (funetAgl), and a module containing REPORT rou- 
tines (reptAgI). These modules are all located in the directory 
/u/john/appl/4GL. If you also have a module containing only 
global variables (globaI.4gl), you must list that module here. 


The Other option allows you to update the three-column 
screen array with headings Other Source, Ext, and Other 
Source Path. This is where you place the filename and location 
of non-4GL source or object code, either using INFORMIX-ESQLlC 
or C. In the example shown in Figure 6-1. you listed a file 
containing C function source code (efune.e) located in 
/u/john/appl/C. You may list up to 30 files in this array. 


The Libraries option permits you to add the name of up to 
ten special libraries that you want to link with your program. 
INFORMIX-4GL calls the C compiler to do the linking and adds 
the appropriate -I prefix, so you should enter only what follows 
the prefix. In Figure 6-1, you have requested only the standard 
C math library. 


The Compile_Options option lets you supply up to ten C 
compile options if desired. You may not enter the -e or -a 
options of e4g1 (see Chapter 1). 


The Exit option returns you to the PROGRAM Menu. 


6-18 The PROGRAM Design Menu 


I. 


The New Option 


The New option of the PROGRAM Menu allows you to create 
a new specification of the program modules and libraries that 
make up the desired application program. You may also 
specify any necessary compiler or loader options. 


PROGRAM 
Modify 
~i. 
Compile 
PI8nned_Com~ile 
Run 
Drop 
Ex;, 


Add 
the 
compilation definition 
of 
8 
4GL 
application 
program 


·.·.·······-----···.············.················.Press CTRL·W for Help····· 


The New option is identical to the Modify option, except that 
you must first supply a name for your program. It then puts 
you with a blank form into the NE\V PROGRAI\1 Menu that 
has the same options as the MODIFY PROGRAM Menu. 


The Compile Option 


The Compile option performs the compilation and linking 
described by the program specification database, taking into 
account the time when files were last updated. It compiles only 
those files that been changed since they were last compiled. 


PROGRAM 
ModIfy 
New 
~..!!!P~ ,Planned_Compile 
Run 
Drop 
E~11 


Camp i I e 
a 
4GL 
a p p lie at ion 
p r og r am 


············----··········--··········---Press CTRl·W for 
Help······ 


INFORMIX-4GL lists each step of the compilation as it occurs. 
See the screen in the following section. 
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The Planned_Compile Option 


Taking into account the time of last change for the various files 
in the dependency relationships, the Planned_Compile 
option prompts for a program name and presents you with a 
summary of the steps that will be executed if you select 
Compile. No compilation actually takes place. 


PR03RANl 
Modify 
New 
Compile 
~ed compile 
Run 
Drop 
Exit 
Show 
the 
planned 
campi Ie 
act ions 
of 
8 
4Gl 
appl ieat ion 
program. 


·················_-·······························Press CTRL·W for Help······ 
Camp j I iog 
INFORMIX-4GL 
sources: 
u 
john 
appl 
4GL"msln 
4g1 
:u 
John 
appl 
4Gl,fur.ct 
4g1 
i u 
j 0 h n " a p pi,' 4G L 
rep t . 4 9 I 
Compiling 
Embedded Sal ,sources 
Camp i r in 9 
w r tho P I ion 5 : 
LinkIng with 
libraries 
m 
Camp iii n 9 
Lin kin got her 
sou r C e 5 : 
u 
john,appl'C,ctunc.c 


If you have made changes in all the components of the program 
listed in Figure 6-1 since the last time you compiled them, 
INFORMIX-4GL presents the previous screen. 
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The Run Option 


The Run option of the PROGRAM Menu is the same as the 
Run option of the MODULE Menu. It presents you with a list 
of compiled programs (with the extension Age) and places the 
highlight on the current program, if any. It then executes the 
program you select. 


PR03RAM 
Mod i f Y 
Ne...... 
Camp i Ie 
P lanned_..Comp 
I I e 
fu_~ 
Dr cp 
Ex I t 
Execute 
a 
4GL 
appl icat ion 
program 


···································--···········Press 
CTRL-W lor 
Help- 


The Drop Option 


The Drop option of the PROGRAM Menu prompts you for a 
program name and removes the compilation definition for that 
program from the syspgrn4g1 database. Your program and 4GL 
modules are not removed. 


PROGRAM" 
Mod j f y 
Ne'oir" 
Camp j Ie 
P lanned-eComp i I e 
Run 
P...!.2.P: 
E): 
I 1 
Drop 
the 
compilation 
definition 
of 
8 
4Gl 
application 
program 


·················································Press CTRl·W lor 
Help- ..... 
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The Exit Option 


The Exit option of the PROGRAM Menu returns you to the 
INFORMIX-4GL Menu. 


PROGRAM 
Modify 
New 
Compi Ie 
Planned_Campi Ie 
Run 
Drop 
~~ 


Returns 
10 
the 
INFORMIX·4GL Menu 


......... ------·.·······.······.················.Press CTRL·W for Help······ 


The QUERY LANGUAGE Menu 


The RDSQL interactive interface is identical to the interactive 
SQL interface of INFORMIX-SQL. You can exercise this 
option only if you have separately purchased and installed 
I::\'FORMIX-SQL on your system. The Query-language option is 
placed at the top level to allow you to test RDSQL statements 
without leaving the INFORMIX-4GL environment. You can also 
create, execute and save SQL scripts. 
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